MCP servers

What it is. A named slot for a remote MCP server. The .swirls file declares the slot; Swirls Cloud holds the server URL and credential; the agent discovers the server's tools at runtime and calls them alongside its workflow tools.

Use it when an agent needs tools from an external service that speaks MCP: observability queries, product analytics, or any vendor with a remote MCP endpoint. Any MCP server URL works.

Works with agents (attached via mcp:), profiles (narrowed per profile), and the project MCP servers page in Swirls Cloud (where slots are bound).

An mcp block declares the slot by name only. No URL, no token, nothing secret in git. This is the same declare-in-git, bind-in-Cloud split as connection blocks.

The mcp block

The mcp block is a top-level declaration. There is no type: field; the keyword identifies the block.

mcp observability {
  label: "Observability"
  description: "Query traces, logs, and metrics"
}

Field reference

There are no required fields. The block name is the slot handle. Names must match ^[a-zA-Z0-9_]+$ and be unique across every file in the project. Unknown keys are rejected.

Attach a slot to an agent

List slot names in the agent's mcp: field. It is a bare-identifier array, same style as tools: and skills:.

secret vendor_keys {
  vars: [OPENROUTER_API_KEY]
}

mcp observability {
  label: "Observability"
}

mcp product_analytics {
  label: "Product analytics"
}

agent sre_assistant {
  label: "SRE assistant"
  secrets: vendor_keys
  model: "openai/gpt-4o-mini"
  mcp: [observability, product_analytics]
  system: @ts {
    return "You investigate production issues. If an MCP tool set is missing, tell the user to connect the slot on the MCP servers page in Swirls Cloud."
  }

  profile readonly {
    mcp: [observability]
  }
}

A profile may narrow mcp: to a subset of the agent's list, the same rule as tools: and skills:.

Two boundaries to know:

• MCP is agent-only. Workflows use http and integration nodes. There is no MCP node type and no MCP syntax inside a workflow.
• Subagents do not inherit slots. A team: member resolves its own mcp: declaration, not the caller's.

Declare in git, bind in Cloud

The .swirls file carries the slot name, label, and description. It never carries a server URL, a token, or a tool list. Bindings live in Swirls Cloud, per project, keyed by slot name. Two projects can bind different servers to the same slot name.

1. Deploy with git push or swirls deploy. Each mcp block appears as a slot on the project's MCP servers page.
2. On that page, bind the slot to a remote MCP server URL and a bearer credential. By default the token is sent as Authorization: Bearer <token>; a binding can instead name a custom auth header that carries the raw token.
3. Tokens are stored encrypted at rest. The URL is validated when you bind it and again on every call; private networks and other unsafe destinations are blocked.

Runtime tool discovery

On the first agent turn of a session, the platform connects to each bound slot, lists its tools, and merges them into the agent's tool set. Every tool the server exposes becomes callable.

Tool naming

Discovered tools are exposed to the model as mcp__<slot>__<tool>. A slot named observability with a server tool queryDataset surfaces as mcp__observability__queryDataset. The prefix keeps names collision-free across servers.

First-turn latency

Discovery adds seconds to the first turn of a session, roughly proportional to the number of bound slots. Later turns reuse the discovered tools. Budget for this if you call the agent through the API and measure first-response time.

Tool lists are live

MCP tools are vendor-maintained. When the remote server adds or removes tools, the agent picks the change up within minutes. A redeploy is never required.

Unbound slots

A slot that is unbound or unreachable yields no tools. The turn continues without them; nothing crashes. Steer this in the system prompt: tell the agent to ask the user to connect the slot on the MCP servers page when its tools are missing.

Validation

swirls doctor validates block shape and references. It never contacts a remote server and never discovers tools, so a misconfigured binding surfaces on the first agent turn, not at doctor time.

Common mistakes

URL or token in the block

The mcp block declares a named slot only. Configuration keys are rejected as unknown properties. Bind the URL and credential on the MCP servers page in Swirls Cloud.

// Incorrect
mcp bad_slot {
  url: "https://mcp.example.com"
  token: "sk-secret"
}

// Correct
mcp good_slot {
  label: "Example"
  description: "Example vendor tools"
}

MCP on a workflow

mcp: is an agent field. There is no MCP node type, and a workflow's tools: cannot carry MCP slots. To call an external HTTP API from a workflow, use an http node.

Profile slots not a subset

A profile's mcp: must be a subset of the agent's mcp:. Listing a slot only in the profile is a validation error.

// Incorrect: product_analytics is not on the agent
agent bad_agent {
  model: "gpt-4o"
  secrets: llm_creds
  mcp: [observability]

  profile analyst {
    mcp: [product_analytics]
  }
}

// Correct
agent good_agent {
  model: "gpt-4o"
  secrets: llm_creds
  mcp: [observability, product_analytics]

  profile analyst {
    mcp: [product_analytics]
  }
}

Expecting doctor to catch a bad binding

Doctor validates the DSL only. An unbound slot, a wrong URL, or an expired token shows up as missing tools on the agent's first turn. Check the MCP servers page in Swirls Cloud when an agent reports its tools are unavailable.

Expecting subagents to inherit slots

Team members do not inherit the caller's mcp: list. Declare mcp: on every agent that needs the tools.

Further reading

• Agents: The agent block, tools, profiles, and how a turn runs.
• Skills: Knowledge packages for agents, the sibling extension point.
• Connections: The same declare-in-git, bind-in-Cloud pattern for OAuth grants.
• Swirls Cloud: Projects, deploys, and the hosted platform.