MCP servers

An mcp_tool reference attaches a connected MCP server to a prompt version. Where a function tool is self-contained, an MCP reference is a pointer: the server is connected once elsewhere, and the version stores only enough to find it. In the dashboard, tools are edited as raw JSON.

Attaching by reference

An mcp_tool reference carries a credential_id for the connected server and an optional tool_names subset:

[
  {
    "kind": "mcp_tool",
    "credential_id": "cred_mcp_orders",
    "tool_names": ["lookup_order", "cancel_order"]
  }
]

• tool_names set: the prompt is scoped to exactly those tools.
• tool_names null: the prompt gets all tools the server exposes, now and later. This is late binding: a tool added to the server after this version was saved comes along automatically, with no prompt edit.

Two properties make this work, and both are deliberate:

• Reference the server, don't inline it. Store the credential_id and nothing else. A version is immutable and readable by the whole team, so anything pasted into one. A URL with a token in it, an authorization header, an API key: cannot be withdrawn afterwards. Tool definitions are stored exactly as written and are not inspected, so nothing stops you doing this by mistake; the discipline is yours.
• No schema is stored on the version. Tool schemas are resolved live from the server at run time, so the prompt follows the server rather than a frozen snapshot.

How it appears in compile

compile() returns the reference on the tools field exactly as stored: it does not fetch schemas or run anything. You resolve the concrete schemas from the connected server and run the tool-calling loop with your provider.

const { tools } = prompt.compile({ question: 'refund status?' });

// tools: [{ kind: 'mcp_tool', credential_id: 'cred_mcp_orders', tool_names: ['lookup_order'] }]

compiled = prompt.compile(question="refund status?")

# compiled.tools:
# [{"kind": "mcp_tool", "credential_id": "cred_mcp_orders", "tool_names": ["lookup_order"]}]