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. 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

Run 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.

Server internals

fluid mcp serve is built on the official MCP Python SDK (FastMCP) and speaks MCP protocol version 2025-06-18. It advertises 16 typed tools — including forge_run, which can drive a full forge from inside the client. Each tool carries an MCP inputSchema, so clients can offer typed autocomplete and validate arguments before dispatch. See the Advanced MCP server guide for the complete authoring-tool catalog and the LLM sampling backchannel.

Consumer: fluid mcp output-port serve

Bind one expose from a FLUID contract and serve it to MCP clients as a governed, read-only data port. This is distinct from fluid mcp serve, which exposes authoring tools — 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 deliberately 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 prints every expose with its kind, binding platform/format, resolved table reference, and which optional tools each one exposes (semantics ⇒ query is advertised). Add --json for machine-readable output.
• doctor 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 / binding issues surface as a clear preflight failure instead of a failed tools/call. Add --json for machine-readable output.

serve syntax

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

The only positional argument is the path to the FLUID contract YAML (or fragment) to serve.

# 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

The four agent tools

The output port advertises a precise, 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, so MCP clients can drive typed autocomplete and validate arguments before dispatch. 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 full enforcement order.

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