MCP Server

fluid mcp serve exposes the staged forge pipeline as a stdio MCP server for clients such as Claude Code, Cursor, Continue, and VS Code MCP integrations. It is a foreground process: no daemon, no HTTP port, and no background service. The server is built on the official MCP Python SDK (FastMCP) and speaks MCP protocol version 2025-06-18.

Start the server

fluid mcp serve

For read-only inspection:

fluid mcp serve --read-only

For scoped write access:

fluid mcp serve \
  --readable-paths ./forge-output \
  --writable-paths ./forge-output \
  --writable-namespaces history,audit

Access controls

Every tools/call is checked by policy before it executes.

Control	Flag	What it does
Read-only mode	`--read-only`	Rejects every mutating tool
Read scope	`--readable-paths PATH[,PATH...]`	Path-based read tools may only inspect files below these roots
Tool allowlist	`--allow-tools TOOL[,TOOL...]`	Hides and blocks tools outside the allowlist
Tool blocklist	`--deny-tools TOOL[,TOOL...]`	Blocks named tools; denial wins over allow
Filesystem scope	`--writable-paths PATH[,PATH...]`	Mutating tools may only write below these roots
Store scope	`--writable-namespaces NS[,NS...]`	Mutating tools may only write listed store namespaces

The default readable and writable path is the current working directory. The default writable namespaces are history,audit.

Tools

Tool	Mode	What it does
`read_logical_model`	read	Load a `.model.json` sidecar and return the typed logical model
`validate_contract`	read	Validate a Fluid contract or forged model sidecar
`diff_models`	read	Compare two logical model sidecars
`search_semantic_memory`	read	Search the semantic memory namespace for similar prior models
`update_entity`	write	Rename or update one logical model entity
`add_relationship`	write	Add a relationship to a logical sidecar
`regenerate_physical`	write	Regenerate the contract and physical fanout from a logical sidecar
`list_source_adapters`	read	List available source-catalog adapters
`list_source_tables`	read	Enumerate tables from a configured source catalog
`inspect_source_table`	read	Inspect a source table profile and metadata
`list_source_lineage`	read	Read lineage from a configured source catalog
`list_source_glossary`	read	Read glossary terms from a configured source catalog
`forge_from_source`	write	Forge a contract and `.model.json` sidecar from a configured source catalog
`forge_run`	write	Run a full `fluid forge` in-process — `mode` is `blank`, `diag`, or `ai`

Every advertised tool includes an MCP inputSchema, so clients can provide typed autocomplete and validate arguments before dispatch.

LLM sampling

The forge_run tool's diag and ai modes need a language model. Rather than configuring a second API key for the server, Forge uses MCP sampling: the server sends the model request back through the MCP connection to the client (Claude Code, Cursor, …), and the client fulfils it with the LLM the user already pays for.

So an agentic IDE can run an AI-assisted forge end-to-end on its own subscription — there is no separate ANTHROPIC_API_KEY or OPENAI_API_KEY for the MCP server. Pair this with fluid scaffold-ide, which writes the MCP server entry straight into the editor's config.

Claude Code example

{
  "mcpServers": {
    "fluid-forge": {
      "command": "fluid",
      "args": [
        "mcp",
        "serve",
        "--read-only"
      ],
      "env": {
        "FLUID_QUIET": "1"
      }
    }
  }
}

Remove --read-only and add both --readable-paths and --writable-paths when you want the client to patch model sidecars or regenerate artifacts inside a specific workspace directory.

Cursor example

{
  "mcp.servers": {
    "fluid-forge": {
      "command": "fluid",
      "args": ["mcp", "serve"],
      "env": {
        "FLUID_QUIET": "1"
      }
    }
  }
}

FLUID_QUIET=1 is important because stdout is reserved for MCP JSON-RPC frames.

Credential handling

The MCP wire format does not accept inline catalog credentials. Source-catalog tools resolve credentials from saved Fluid source configs, environment variables, or explicit credential IDs that were configured outside the MCP call.

Set up a source first:

fluid ai setup --source snowflake --name snowflake-prod

Then an MCP client can call forge_from_source with source: "snowflake" and credentials.credential_id: "snowflake-prod" without receiving raw secrets.

Certification

Before publishing a release, run:

PYTHONPATH=. python scripts/mcp_client_certify.py

The certification script checks the JSON-RPC lifecycle, tools/list, tools/call, MCP Inspector when available, and Claude Code config health when the claude CLI is installed. Optional client checks are skipped when their tools are not installed; protocol failures fail the script.