fluid mcp

fluid mcp exposes Fluid Forge over the Model Context Protocol so MCP-compatible clients (Claude Code, Claude Desktop, Cursor, Continue, VS Code, MCP Inspector, and your own agents) can talk to it. This page is the flag and subcommand reference. The Advanced MCP server guide explains the governance model and the tool catalog, and the walkthrough serves a data product end to end.

There are two distinct servers under this command, with two different threat models:

fluid mcp                       # interactive guide (no subcommand → friendly panel)
fluid mcp serve [...]           # producer-side authoring server
fluid mcp output-port serve ... # consumer-side data-access server

Producer: fluid mcp serve

Runs the authoring MCP stdio server so an MCP client can inspect, validate, and edit forge artifacts. It is a foreground process — no daemon, no HTTP port, no background service.

Syntax

fluid mcp serve [--read-only]
fluid mcp serve [--allow-tools TOOL[,TOOL...]] [--deny-tools TOOL[,TOOL...]]
fluid mcp serve [--readable-paths PATH[,PATH...]] [--writable-paths PATH[,PATH...]]
fluid mcp serve [--writable-namespaces NS[,NS...]] [--allow-inline-credentials]

Recommended start

For review-only client sessions:

FLUID_QUIET=1 fluid mcp serve --read-only

For a scoped workspace where the client may update generated model sidecars and regenerate artifacts:

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

FLUID_QUIET=1 keeps stdout reserved for MCP JSON-RPC frames.

Access controls

Inline catalog credentials are blocked by default. Configure source credentials outside MCP and pass credential ids from the client.

Each tool carries an MCP inputSchema, so clients can offer typed autocomplete and validate arguments before dispatch. The tool catalog and the LLM sampling backchannel are in the Advanced MCP server guide.

Tool errors

forge_run reports an anticipated failure — an IDE that does not advertise the sampling capability, say — as the SDK's own ToolError. Its message names the capability and its two ways out: mode='blank', or shelling out to fluid forge --agent --blank. (since 0.15.0) On MCP SDK 2.x an exception that is not a ToolError reaches the client as the generic text Error executing tool forge_run, so the tool raises ToolError to keep its message.

Supported MCP SDK versions

Both servers run on the official mcp Python SDK.

The protocol version is negotiated by the SDK at initialize, not fixed by Forge. A client built on that mcp 2.3.0 was offered 2025-11-25 by both servers.

Consumer: fluid mcp output-port serve

Binds one expose from a FLUID contract and serves it to MCP clients as a governed, read-only data port. This is distinct from fluid mcp serve: the output port queries production data, so its threat model and policy surface differ entirely.

The server is read-only by default and exposes a small surface: an agent can describe the data product, sample a few rows, and run a predeclared semantic query. Free-form SQL (query_sql) is OFF unless you opt in with --allow-sql.

The output-port subcommands

fluid mcp output-port list   <contract>   # list the exposes this server can serve
fluid mcp output-port doctor <contract>   # preflight: load the driver, run a health check
fluid mcp output-port serve  <contract>   # run the MCP server bound to one expose

list

fluid mcp output-port list <contract> [--env ENVIRONMENT] [--json]

Prints every expose with its kind, binding platform/format, resolved table reference, and which optional tools each one exposes (semantics ⇒ query is advertised):

Exposes in contract.fluid.yaml (1 total):

  • customer_segments  (table)
      title:  Customer Segments
      engine: local/csv → ./customers.csv
      tools:  describe, sample, query  [semantics, expose.mcp]

--json prints the same list as JSON, with exposeId, kind, title, platform, format, tableReference, hasSemantics and hasMcpOverrides per expose.

doctor

fluid mcp output-port doctor <contract> [--expose-id EXPOSE_ID] [--env ENVIRONMENT] [--json]

Loads the engine driver for one expose and runs its health_check (a cheap SELECT 1 round-trip). Run it before wiring a client so credential, network and binding problems surface as a preflight failure instead of a failed tools/call. --expose-id is optional when the contract has a single expose.

✅ fluid mcp output-port doctor: expose='customer_segments' (OK)
  contract: /work/demo/contract.fluid.yaml
  binding:  local/csv → customer_segments
  tools:    describe, sample, query
  ✓ driver_load: duckdb
  ✓ engine_health: duckdb-ok

With several exposes and no --expose-id, the check fails with Contract has 2 exposes; pass --expose-id to pick one and lists the available ids.

serve syntax

fluid mcp output-port serve <contract> [options]

The only positional argument is the path to a FLUID contract YAML: a flat contract, or the root file of a contract composed with $ref, whose references are resolved (see fragment-first contracts for the authoring tools that take a contract_path). An individual fragment file is not a contract: fluid mcp output-port list fragments/exposes/<id>.yaml printed No exposes in ... and exited 0.

# Minimal — one expose in the contract, stdio transport, read-only.
fluid mcp output-port serve ./contract.fluid.yaml

# Bind a specific expose by id.
fluid mcp output-port serve ./contract.fluid.yaml --expose-id customer_segments

# Enable free-form SQL for a trusted internal copilot.
fluid mcp output-port serve ./contract.fluid.yaml --allow-sql

# Serve over HTTP/SSE for a network deployment (front with a proxy — see below).
fluid mcp output-port serve ./contract.fluid.yaml \
  --transport http --host 127.0.0.1 --port 8765

serve flags

Data outside the contract directory

By default the server may read only under the directory of the contract file. A binding that points elsewhere fails each tool call with UnsupportedBindingError, and the audit record names the path. Reproduced with a CSV in data/ and the contract in contract/, started from their common parent, with location.path: data/customers.csv:

.
├── contract/open.fluid.yaml
└── data/customers.csv

fluid mcp output-port serve contract/open.fluid.yaml

The audit record for the failed sample call:

decision: tool_error   reason: UnsupportedBindingError
annotatedMessage: binding.location.path /work/data/customers.csv is outside --readable-paths

Name the directory that holds the data:

fluid mcp output-port serve contract/open.fluid.yaml --readable-paths ./data

Pass several roots with commas (--readable-paths ./data,./warehouse). The flag replaces the default, so if the contract's own directory also holds files the binding reads, list it too.

The agent tools

The output port advertises a bounded surface derived from the bound expose's shape. The query tool is only advertised when the expose declares a semantics block; query_sql is only advertised with --allow-sql.

Every tool ships an MCP inputSchema. Each tools/call is checked against the contract's agentPolicy (allowed/denied models + use-cases), the tool allow/deny lists, a sliding-window rate limit, a token budget, a circuit breaker, and a concurrency cap — see the deep dive for the enforcement order.

When allowedModels is set and the caller declared no model at initialize, the call is denied. Measured against a CSV-backed expose with allowedModels: ["claude-sonnet-4-6", "gpt-4.1-mini"], an anonymous sample returned:

{
  "error": "AgentPolicyDenied",
  "tool": "sample",
  "reason": "missing-model-identity",
  "message": "denied by agentPolicy (missing-model-identity); see audit trail for the full decision."
}

The decision is also written to the audit trail as a data_access event with decision: deny.

exposes[0].policy: Additional properties are not allowed ('rowFilters' was unexpected)

Wire it to a client

{
  "mcpServers": {
    "customer-segments": {
      "command": "fluid",
      "args": [
        "mcp", "output-port", "serve",
        "/abs/path/to/contract.fluid.yaml"
      ],
      "env": { "FLUID_QUIET": "1" }
    }
  }
}

FLUID_QUIET=1 is important because stdout is reserved for MCP JSON-RPC frames; all human-facing notices go to stderr.

Related guides

• Advanced MCP server guide — runtime governance, auth modes, drivers, IAM compilers, rate-limit / circuit-breaker / audit internals.
• Walkthrough: MCP output port — serve the example DuckDB product end-to-end and watch PII masking + an agentPolicy deny in action.
• AI Forge And Data-Model Journeys
• Forge Memory Guide