MCP

Declare MCP servers with mcp(...). The map shape matches Agent Plugins mcpServers: each key must equal that server's name.

import { Agent, mcp } from "@nylorun/agents";

export const assistant = Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "Use the available tools.",
}).use(
  mcp({
    github: {
      name: "github",
      type: "streamable-http",
      url: "https://mcp.example.com/github",
    },
  }),
);

Transports follow Agent Plugins MCP servers: stdio, streamable-http, and sse. Pass { id: "…" } as the second argument to override the default capability id "mcp".

mcp(
  {
    local: {
      name: "local",
      type: "stdio",
      command: "npx",
      args: ["-y", "@example/mcp-server"],
    },
  },
  { id: "docs-mcp" },
)

Runtime discovers tools on the session's first turn and pins them in mcpSnapshot. The snapshot contains no secrets. A later session PUT may replace vaultIds and credentialSelections; agentId, ownerUserId, and info stay the creation identity.

URL-bound credentials for outbound MCP calls belong in an end-user vault with the same ownerUserId as the session. The host vault is not attachable to a session.

A mismatched key and name throws McpError (mcp.name-mismatch). An empty map throws mcp.empty.

Next step