MCP Server

Fluid Forge ships two Model Context Protocol servers under fluid mcp:

• fluid mcp serve — the producer / authoring server. Exposes the staged forge pipeline as stdio MCP tools so an editor's AI can inspect, validate, and edit contracts.
• fluid mcp output-port serve — the consumer / data-access server (the flagship output-port capability). Binds one expose of a published contract and serves a small, governed, read-only surface to AI agents.

The first half of this page covers the authoring server. The second half is a deep dive on the output port's runtime governance — the part that takes reading several files to learn.

Authoring server — fluid mcp serve

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                 # full surface
fluid mcp serve --read-only     # read-only inspection

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.

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

Authoring tools

The authoring server advertises 16 typed tools:

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.

Client config examples

Claude Code (mcp_servers.json):

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

Cursor (settings.json):

{
  "mcp.servers": {
    "fluid-forge": {
      "command": "fluid",
      "args": ["mcp", "serve"],
      "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. 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 by default. Source-catalog tools resolve credentials from saved Fluid source configs, environment variables, or explicit credential IDs configured outside the MCP call.

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

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.

Output port — fluid mcp output-port serve

The output port is the inverse of the authoring server. Where authoring writes filesystem paths and store namespaces, the output port reads production data: it binds one expose of a contract and serves a bounded, read-only surface (describe / sample / query / gated query_sql) to an AI agent. Because it touches real data, its entire value is in the governance the contract carries — enforced at runtime, on every call, with no extra wiring.

For the flag reference and a quick start, see fluid mcp in the CLI reference. For a hands-on walkthrough, see Walkthrough: MCP output port. The rest of this page is the architecture.

The contract is the policy

Nothing about the gateway's governance is configured on the command line by default — it is read from the bound expose. The CLI flags (--allow-models, --max-sample-rows, …) are operational overrides for incident response; the contract is the source of truth, and the audit trail records which one won via a policySource field (contract, cli, or default).

The expose blocks the gateway reads:

exposes:
  - exposeId: customer_segments
    contract:
      schema:
        - { name: customer_id, type: STRING, sensitivity: cleartext }
        - { name: email,       type: STRING, sensitivity: pii }      # value-redacted
        - { name: segment,     type: STRING }
    semantics:                       # enables the `query` tool
      measures:  [ { name: customer_count, agg: count_distinct, expr: customer_id } ]
      dimensions: [ { name: segment, type: categorical } ]
      metrics:   [ { name: active_customers, type: simple, measure: customer_count } ]
    binding:
      platform: local
      format: csv
      location: { path: ./customers.csv, table: customer_segments }
    policy:
      agentPolicy:                   # runtime model / use-case / token gates
        allowedModels:  [ claude-haiku-4-5-20251001, gpt-4o-mini ]
        allowedUseCases: [ analysis, qa ]
        deniedUseCases:  [ training, fine_tuning ]
        maxTokensPerRequest: 4096
        maxTokensPerDay: 50000
        canStore: false
        auditRequired: true
      rowFilters:                    # per-tenant row-level security
        - { column: tenant_id, equals: "${caller.tenant_id}" }

Per-tools/call enforcement order

Every tools/call runs through a fixed gauntlet. The order is deliberate: cheap, abuse-resistant gates fire first so a runaway agent can't burn audit storage hammering denied tools.

1. Identity binding. The caller's model_id, useCase, and any extra clientInfo fields are read from the MCP initialize handshake and bound to the session on the first call. Missing identity is treated as missing-model-identity (fail-closed at the model gate).
2. Rate limit. A sliding-window deque caps calls per window (default 60 calls / 60s). Over the cap returns a RateLimitExceeded envelope.
3. agentPolicy gate. OutputPortPolicy.check_tool_call evaluates, first-deny-wins: tool denylist → tool allowlist → model denylist → use-case denylist → model allowlist → use-case allowlist. A deny returns an AgentPolicyDenied envelope.
4. Circuit breaker. If recent driver failures tripped the breaker, the call fast-fails with a CircuitOpen envelope instead of queueing behind another doomed connection.
5. Token budget (pre-check). agentPolicy.maxTokensPerDay is checked against a rolling 24-hour counter. Over budget returns TokenBudgetExceeded.
6. Backpressure. An asyncio.Semaphore bounds concurrent dispatches (default 8) so a runaway agent can't saturate the engine connection pool.
7. Dispatch + post-checks. The tool runs in an executor (driver SDKs are blocking). After it returns, agentPolicy.maxTokensPerRequest is checked against the actual response size, the daily counter is topped up, and the circuit breaker records success/failure.

Every decision — allow and deny — is written to the audit trail, tagged with the policySource that produced it (rate-limit, circuit-breaker, token-budget, contract, cli, …).

agentPolicy runtime gates

The gateway makes the previously advisory agentPolicy block load-bearing. On every call it evaluates:

CLI overrides (--allow-models, --deny-models, --allow-use-cases, --deny-use-cases) replace the contract values entirely (not merged) so the override is intentional and grep-able in the audit trail as policySource: cli.

Authentication modes

Identity is resolved once at gateway start from FLUID_MCP_AUTH_MODE. There are three modes plus an explicit opt-out:

mTLS is handled by the reverse proxy in front of the gateway, not inside it. The proxy terminates the client cert and forwards X-Client-CN + X-Client-Fingerprint; the gateway reads those headers (extract_mtls_identity) and stamps the cert identity onto the audit event alongside the JWT claims, so a call carries both "which token" and "which cert."

FLUID_MCP_JWT_CLAIM_MAPPING is a comma-separated claim=attr list, e.g. sub=principal,https://fluid/model=model,https://fluid/tenant=tenant_id. Mapped claims land in caller_attributes, which is exactly what rowFilters ${caller.<attr>} placeholders resolve against — so on the JWT path, per-tenant filters resolve cryptographically rather than from self-attested clientInfo.

PII / PHI value redaction

Columns marked sensitivity: pii, sensitivity: phi, or sensitivity: sensitive in expose.contract.schema keep their key visible (the agent still sees the field exists and can write COUNT(DISTINCT …) aggregates) but their values are replaced with the constant [REDACTED-PII] before the row leaves the gateway.

This happens at the driver boundary — EngineDriver.project() masks every row from sample, query, and query_sql alike. It is distinct from columnRestrictions, which drops a column wholesale:

Both are alias-proof on the free-form path. Masking matches by output column name, so SELECT email AS x would otherwise sneak a PII value past it. The query_sql compiler closes that hole by rejecting any reference to a restricted or PII column at compile time (string literals are stripped first, so WHERE label = 'email' doesn't false-positive). The agent cannot alias the column away.

Row-level security — policy.rowFilters

For per-tenant isolation, declare policy.rowFilters[] on the expose. Each filter compiles to a parameterised WHERE clause appended to sample / query reads, bound to the caller's identity:

policy:
  rowFilters:
    - { column: tenant_id, equals: "${caller.tenant_id}" }
    - { column: region,    in:     "${caller.regions}" }

${caller.<attr>} placeholders resolve from caller_attributes — populated from the MCP clientInfo extras over stdio, or from JWT claims / the mTLS cert over HTTP. The supported operators are equals (scalar) and in (non-empty list); values are always bound as parameters, never interpolated.

Missing identity fails closed. If a filter references ${caller.tenant_id} and the caller never supplied it, the read raises RowFilterIdentityMissing and serves no rows — the gateway prefers no rows to wrong rows.

The five engine drivers

Drivers are keyed on (binding.platform, binding.format) and built lazily, so describe works even when cloud credentials are missing. Out-of-tree drivers can register via register_driver(("databricks", "delta_table"), DatabricksDriver) from a private wheel — no core edits.

The query compiler emits portable :p_<index> placeholders and each driver re-renders them to its dialect; every interpolated identifier passes through _sql_safety.validate_ident, and the rendered statement is swept for injection markers (;, --, /*, */) and banned keywords (UNION, DROP, …) as defence-in-depth.

Cloud-IAM compilers — defending the bypass path

The gateway only governs traffic through it. An analyst querying the warehouse directly with their own role is a bypass. fluid_build.output_ports.iam_compiler closes that gap by compiling the same agentPolicy + rowFilters contract into cloud-native policy you apply warehouse-side:

Each CompiledPolicy carries a warnings list naming the agentPolicy fields the target can't enforce natively (e.g. a ${caller.tenant_id} with no warehouse primitive), so operators know exactly which gap to plug with another control.

Resilience — rate limit, circuit breaker, backpressure

All three are in-process (single-replica) and tunable by environment variable. Set the limit to 0 to disable.

On graceful shutdown (SIGTERM / SIGINT) the gateway drains in-flight calls (up to 5s) before tearing down driver connections.

Audit trail, rotation, and the webhook forwarder

Every gateway decision writes a data_access audit event to ~/.fluid/store/audit/ (override the root with FLUID_AUDIT_ROOT). Writes are atomic (stage-to-temp then rename) and use a microsecond + pid + process-tag + monotonic-counter suffix so concurrent decisions — even across a gateway fleet sharing a network volume — never overwrite each other. The local-disk copy is always the source of truth.

Rotation runs automatically at gateway startup, bounded by two independent knobs:

Webhook forwarding mirrors every event to a central SIEM aggregator (Splunk HEC, Datadog, Elastic, Loki) for multi-replica HA. It is best-effort and fire-and-forget on a daemon thread — webhook failures never block the local write.

When FLUID_STORE_BACKEND points at a non-file backend (Postgres / Sqlite / Vector), each event is also written through the Store under the audit namespace — again without losing the on-disk fallback.

Audit events are auto-correlated with the rest of the forge-cli pipeline: the gateway resolves the same cross-stage run_id (FLUID_RUN_ID) other CLI stages honour and stamps it onto both the audit payload and an OpenTelemetry span (fluid.mcp.call_tool) when an exporter is configured.

HTTP and SSE transport, and the reverse-proxy templates

--transport http serves the gateway over MCP-SSE (mcp.server.sse.SseServerTransport + Starlette + uvicorn, transitive deps of the mcp extra). Clients connect at http://host:port/sse. Identity binding is identical to stdio — only the wire differs.

The HTTP transport has no built-in TLS or strong identity on its own. Front it with a reverse proxy. The repo ships ready-to-edit templates at examples/mcp-output-port-docker/proxy/:

• Caddyfile — Caddy 2.x: automatic TLS, client_auth { mode require_and_verify } mTLS, a proxy-layer bearer-token check, flush_interval -1 for SSE, and header_up X-Client-CN {tls_client_subject} / X-Client-Fingerprint {tls_client_fingerprint} so the gateway records cert identity.
• nginx.conf — equivalent for nginx shops: ssl_verify_client on, proxy_buffering off + long read/send timeouts for SSE, and the same X-Client-CN / X-Client-Fingerprint forwarding.

This is defence-in-depth — every layer stops a different failure:

Environment variables (output port)

Related guides

• fluid mcp CLI reference — every flag, copy-paste examples, the four agent tools.
• Walkthrough: MCP output port — serve the example DuckDB product end-to-end; watch PII masking and an agentPolicy deny.
• Governance — contract-level policy authoring.
• Environment variables — the full forge-cli env-var index.