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 --read-only     # inspection only
fluid mcp serve                 # full surface, scoped to the working directory

Every tools/call is checked by policy before it runs. The flags that scope it (--read-only, --allow-tools, --deny-tools, --readable-paths, --writable-paths, --writable-namespaces, --allow-inline-credentials) are documented once, in the fluid mcp CLI reference. This page covers what the tools do and how the output port enforces governance.

Authoring tools

The authoring server advertises these tools. With --read-only, the tools marked write are not advertised:

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

Fragment-first contracts

A contract split into fragments keeps $ref stubs in its root file (see Contract fragments and Composing a contract with $ref). fluid validate, fluid plan and fluid mcp output-port serve resolve those references. As of 0.18.1, the authoring tools that take a contract_path read the file as written and do not resolve $ref stubs. validate_contract takes contract_path (or logical_path) and no inline contract; score_contract_quality and enrich_contract_suggestions accept either contract_path or an inline contract object.

On a root that holds $ref stubs, validate_contract reports errors that fluid validate does not:

{"score": 0, "passes_schema": false, "issues": [
  {"message": "builds[0]: Additional properties are not allowed ('$ref' was unexpected)", ...},
  {"message": "exposes[0]: 'exposeId' is a required property", ...}, ...]}

fluid validate on the same file prints ✅ Valid FLUID contract (schema v0.7.5). Resolve the references first and point the tool at the result:

fluid bundle contract.fluid.yaml --out runtime/contract.bundled.yaml

With contract_path: runtime/contract.bundled.yaml, the same call returns passes_schema: false only for the findings the contract really has. An editor agent driving fluid mcp serve on a project that fluid forge split into fragments needs this step, or it scores $ref stubs and not the contract.

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 semantics block that enables the query tool is described in Semantic layer.

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

Per-tenant row filters are also read from policy.rowFilters, with a caveat about schema validation: see Row-level security.

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, useCase and any extra attributes are read from the MCP initialize handshake, from the fluid block of the client's capabilities.experimental (and, on MCP SDK 1.x, from extra clientInfo fields), and resolved again on every tool call from that request's own context, never cached on the shared session (on HTTP/SSE one process serves many clients, so a cached identity would carry one client's agentPolicy principal and tenant row filter onto the next). 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, in the precedence listed under Decision precedence and reason codes. 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, …) and, (since 0.15.0), with the callerJurisdiction the decision was made under.

{"capabilities": {"experimental": {"fluid": {"model": "claude-haiku-4-5-20251001", "useCase": "analysis", "tenant_id": "t1"}}}}

⚠️  fluid mcp output-port: caller model_id is self-attested via MCP clientInfo. Do not expose this gateway over an untrusted network until P3 (OAuth/mTLS identity) ships. See https://agenticstiger.github.io/forge_docs/concepts/agent-policy.html

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.

Decision precedence and reason codes (since 0.15.0)

Since 0.15.0 every agentPolicy decision comes from one function (fluid_build/policy/decision.py::decide) over a closed vocabulary of reason codes, and precedence is data rather than an accident of statement order. CHECK_ORDER, in full:

1. tool-not-allowed — denied outright, or absent from a declared tool allowlist.
2. missing-caller-jurisdiction
3. in-denied-jurisdiction
4. not-in-allowed-jurisdictions
5. missing-model-identity
6. in-deniedModels
7. in-deniedUseCases
8. not-in-allowedModels
9. missing-use-case-with-allowlist
10. not-in-allowedUseCases

plus allowed when nothing fires. Two principles set that order: bounded surfaces are checked first, and an explicit denial beats absence from an allowlist. Jurisdiction sits above the identity gates on a third — a legal constraint outranks a usage constraint as the reported reason, because "your model is not on the allowlist" describes the least important thing wrong with a request from a caller who may not receive the data at all.

The wire values are the existing kebab-case strings, so a caller comparing against "tool-not-allowed" keeps working. What is new is that an unenumerated reason now raises instead of quietly becoming a reason nobody defined.

A decision record (Decision.to_record()) carries allow, reasonCode, the request identity, and (since 0.15.0) three new fields:

Portable conformance vectors ship inside the wheel at policy/data/vectors/agent-policy-vectors.json, so a consumer can check their own gate without cloning the repo. The digest is reachable from OutputPortPolicy.policy_digest() and Decision.to_record(), and since 0.15.0 every data_access audit record carries it as policyDigest, alongside policySource and callerJurisdiction.

Caller-jurisdiction enforcement (since 0.15.0)

Before 0.15.0, sovereignty bound provisioning and nothing else: a contract declaring jurisdiction: EU refused to provision into us-east-1, then answered a tool call from a caller sitting there. Since 0.15.0 the gateway derives a query-time caller-jurisdiction rule from the contract's own sovereignty block.

Enforced, not advisory, and on by default. There is no flag to switch it on and none to switch it off — the escape hatches are all in the contract:

Verified claims only, and fail-closed. The claim is admissible only from request.scope["fluid_auth_attrs"], which the HTTP _AuthMiddleware writes after a credential validates — never from the caller's self-attested clientInfo. In practice that means the jurisdiction claim of a verified JWT: a shared token and a proxy-forwarded client certificate carry no jurisdiction. A client typing jurisdiction: "EU" into its own handshake satisfies nothing and collapses to the same missing-caller-jurisdiction denial as no claim at all. There is no no-auth fallback, on purpose. Matching is exact and case-sensitive: a verified "eu" against a contract pinning "EU" is refused.

jurisdiction is also one of the default JWT claim mappings, and it is the one default whose absence closes the gate rather than widening it: an operator whose IdP calls the claim something else locks themselves out of a jurisdiction-pinned contract until they map it.

Authentication modes

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

Only a verified JWT binds identity. With shared-token, the gateway knows that the caller held the shared secret and nothing else: once the token is enforced, any model, useCase or tenant attribute the client declares for itself is dropped. A contract with an allowedModels or deniedModels gate then denies every call as missing-model-identity, and one with allowedUseCases as missing-use-case-with-allowlist. Use jwt when the gates must see who is calling.

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.

(since 0.15.0) The value merges over the default mappings instead of replacing them. Those defaults are:

PII / PHI value redaction

Columns marked sensitivity: pii or sensitivity: phi 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, the gateway reads policy.rowFilters[] from 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}" }

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

{"rows": [{"customer_id": 1, "email": "[REDACTED-PII]", "segment": "gold", "tenant_id": "t1"}], "rowCount": 1}

${caller.<attr>} placeholders resolve from caller_attributes: the fluid block of the client's declared capabilities over stdio or over HTTP with no auth mode enforced, or the mapped claims of a verified JWT over HTTP with FLUID_MCP_AUTH_MODE=jwt. A client certificate checked by a proxy does not supply tenant_id; see Authentication modes. 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.

The record is written for every decision, whether or not agentPolicy.auditRequired is set; auditRequired only makes the gateway announce the audit location at startup. This is a real allow record (the file is <timestamp>_<suffix>_data_access.json):

{
  "event": "data_access",
  "payload": {
    "argumentSummary": { "limit": 5 },
    "callerJurisdiction": null,
    "contractPath": "/work/customers/contract.fluid.yaml",
    "decision": "allow",
    "exposeId": "customer_segments",
    "modelId": "claude-haiku-4-5-20251001",
    "policyDigest": "jcs-sha256:1cbcc442095182120ff06255dcded1185fc5f824a8cfc195ddeef807b8b2c6e3",
    "policySource": "contract",
    "reason": null,
    "runId": "e230144051ba",
    "tool": "sample",
    "useCase": "analysis"
  },
  "timestamp_utc": "2026-10-05T01:08:05.577382+00:00"
}

A denial by the policy gate has the same keys, with decision: "deny" and a reason. A denial by the rate limit, the circuit breaker or the token budget carries a shorter set (tool, exposeId, modelId, useCase, decision, reason, policySource, argumentSummary, runId): no contractPath, callerJurisdiction or policyDigest, and a policySource of rate-limit, circuit-breaker or token-budget.

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. With no auth mode enforced, identity binding is the same as over stdio: the client declares it. With one enforced, only verified attributes bind, as described under Authentication modes.

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}, which forward the certificate's subject and fingerprint as the headers described under Authentication modes.
• 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:

The model, use-case and tenant rows tell a legitimate client from another one only when the caller's identity is verified, which is FLUID_MCP_AUTH_MODE=jwt. Behind the shared token the gateway drops what the client declares about itself, and a client certificate supplies none of those attributes; see Authentication modes.

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, including sovereignty.
• Environment variables — the full forge-cli env-var index.