MCP Integration

What MCP integration provides

MCP (Model Context Protocol) integration allows Syndicate Code to connect to external tool servers that expose capability surfaces callable by the runtime. MCP servers are external processes — because they operate outside the Syndicate Code process boundary, all MCP tool invocations must pass through the full governed execution lifecycle before any external call is made (mcp_and_plugin_integration_spec.md §1).

Design principles

MCP integration follows eight principles (mcp_and_plugin_integration_spec.md §3):

• MP-001: MCP tools are governed tools — every invocation traverses the full lifecycle
• MP-002: MCP servers are untrusted by default
• MP-003: Capability declaration before invocation
• MP-004: Tool identity is version-pinned
• MP-005: Dynamic tool surfaces require stricter governance
• MP-006: Permit validation occurs at the MCP boundary
• MP-007: Capability scope is declared, not inferred
• MP-008: Raw request and response are audit evidence

MCP vs. specialists

MCP tools and specialists are both governed but differ in structure (mcp_and_plugin_integration_spec.md §4):

Despite structural differences, MCP tools and specialists are equivalent in governance obligations. Both must pass through full canonicalization, receive a permit, undergo boundary permit validation, emit audit evidence, and adhere to declared scope.

Registering an MCP server

An MCP server must be registered before any tool it exposes may be invoked. Registration is a control-plane operation initiated by the operator — runtime components may not self-register MCP servers.

syndicate mcp add filesystem \
  --url http://localhost:5050 \
  --transport sse \
  --trust-tier 0 \
  --capability-declaration ./mcp/filesystem.yaml

Registration requires (mcp_and_plugin_integration_spec.md §5.2):

• server identity (stable name, not ephemeral)
• server endpoint or process configuration
• server version
• capability declaration
• declared trust tier request (informational; actual tier is assigned by policy)
• operator-provided justification for inclusion
• policy tags indicating applicable deployment modes

Transport types

Capability declaration

Before any tool on an MCP server may be invoked, the server must provide a capability declaration that the control plane has accepted and recorded (mcp_and_plugin_integration_spec.md §6).

Each tool in the declaration must include:

• tool name (canonical within the server's namespace)
• tool version or schema version
• parameter schema (typed, with required vs. optional fields)
• declared side-effect classes (read, write, execute, network, secret access, other)
• declared resource scopes
• required permissions or credential classes
• declared output schema or type
• idempotency classification (idempotent, non-idempotent, unknown)
• declared failure modes

The control plane validates the declaration for structural completeness and policy compatibility before accepting it. Invocation of an undeclared tool is prohibited regardless of approval status.

Static vs. dynamic surfaces

A server with a static tool surface declares a fixed set of tools at registration. This is the preferred form.

A server with a dynamic tool surface exposes a tool list that may change at runtime. Dynamic surfaces require:

• self-declaration as dynamic in registration
• mechanism for the control plane to re-query the current tool surface
• re-declaration and re-acceptance cycle before new or changed tools may be invoked
• policy may restrict dynamic surfaces to specific deployment modes

Tool identity

Every MCP tool has a canonical identity (mcp_and_plugin_integration_spec.md §8.1):

<server-identity>/<tool-name>@<server-version>#<declaration-version>

Where:

• server-identity is the stable registered name of the MCP server
• tool-name is the name as declared in the capability declaration
• server-version is the version string from the server registration record
• declaration-version is the version of the accepted capability declaration

Tool identity must be stable for the lifetime of a server registration version. A server version upgrade produces new tool identities for all tools on that server.

Verify a tool's canonical identity and current trust state with:

syndicate trust list --output json

Governed invocation path

Every MCP tool invocation must follow the full governed execution lifecycle (mcp_and_plugin_integration_spec.md §9):

1. Proposal Intake — runtime generates a proposal referencing the canonical tool identity
2. Canonicalization — control plane resolves tool identity, normalizes arguments
3. Policy Evaluation — evaluated against the canonical request including declared side-effect classes
4. Evidence Preparation — control plane finalizes evidence including declaration version
5. Approval Determination — untrusted servers require explicit approval
6. Approval Recording — bound to the canonical tool identity including declaration version
7. Permit Issuance — references the canonical tool identity and declaration version
8. MCP Boundary Validation — MCP adapter validates the permit before issuing the protocol call
9. MCP Protocol Call — adapter issues the tool call to the external server
10. Result Recording — MCP response recorded as audit evidence

The MCP adapter layer must not issue protocol calls outside this lifecycle. Direct MCP calls bypassing the control plane are prohibited.

Permit validation at the MCP boundary

Before constructing or transmitting any MCP protocol call, the MCP adapter validates (mcp_and_plugin_integration_spec.md §10):

• permit authenticity (integrity check)
• permit expiry
• permit-to-tool identity match
• permit-to-argument scope match
• declared side-effect class match
• workflow lineage match
• trust state eligibility
• checkpoint status

If any validation step fails, the MCP adapter must not transmit the call. The failure is recorded as a denied execution event.

The MCP adapter layer holds no ambient authority — it holds no credentials or access rights exercisable outside a valid permit context.

Trust model

Default trust state

Every MCP server begins in an untrusted state. Every tool on an MCP server begins in an untrusted state independently of the server's trust state (mcp_and_plugin_integration_spec.md §11).

Trust is maintained per boundary — the record for tool A on server X is independent of the record for tool B on server X.

Trust accumulation

Trust is earned through evidence accumulation (mcp_and_plugin_integration_spec.md §11.3):

• repeated successful permit validations
• repeated execution within declared scope
• stable parameter behavior consistent with declared schema
• stable side-effect behavior consistent with declared side-effect classes
• absence of scope violations across executions
• stable server version without surprise changes

Trust violation handling

On any trust violation at the MCP boundary (mcp_and_plugin_integration_spec.md §11.5):

• the affected (server, tool) trust record resets to untrusted immediately
• confidence score is demoted per policy
• all active permits for the affected tool are invalidated
• control plane emits a trust-violation audit event
• envelopes relying on the violated tool may be invalidated per policy

A violation by one tool does not automatically reset the trust of other tools on the same server unless policy specifies server-level trust contamination rules.

Sandboxing

MCP servers are external processes. The runtime must treat them as untrusted processes regardless of trust tier (mcp_and_plugin_integration_spec.md §12).

At minimum:

• MCP servers must run as separate OS processes
• MCP servers must not share the runtime process's filesystem namespace beyond declared resource scopes
• network access by MCP servers must be subject to egress policy enforcement
• MCP server processes must not be granted ambient credentials; credentials must be injected per invocation

If required isolation cannot be established for an MCP server invocation, execution must be denied.

Version management

MCP server version is part of tool identity. A version change produces new tool identities for all tools on that server (mcp_and_plugin_integration_spec.md §13).

When an MCP server version changes:

• operator must submit an updated registration record
• server must re-submit a capability declaration
• control plane must re-accept before any invocations are allowed
• new approvals must be obtained for all tools on the updated server

Downgrading to a prior version is treated identically — prior approvals are not automatically restored.

Managing MCP servers

# List registered servers
syndicate mcp list

# Show a server's full record
syndicate mcp show filesystem

# Test connectivity and capability validation
syndicate mcp test filesystem

# Remove a server (invalidates dependent permits)
syndicate mcp remove filesystem

Failure handling

Required invariants

• INV-MP-001 — No MCP tool may be invoked without an accepted capability declaration
• INV-MP-002 — No MCP invocation may proceed without a valid permit bound to the resolved canonical tool identity
• INV-MP-003 — No MCP protocol call may be transmitted before MCP boundary permit validation succeeds
• INV-MP-004 — No MCP server may be registered without an operator-initiated control-plane registration record
• INV-MP-005 — No approval for an MCP tool invocation survives an MCP server version change
• INV-MP-006 — No MCP tool may exercise side-effect classes or access resource scopes not declared in its accepted capability declaration