MCP servers

Mount any Model Context Protocol server as a tool group. Skawld launches the server as a child process (stdio) or connects over Streamable HTTP, lists its tools, and exposes each one to the agent under an mcp__<server>__<tool> name.

import { Agent } from "@skawld/agent-sdk";

const agent = new Agent({
  provider,
  model: "claude-opus-4-5",
  mcpServers: {
    postgres: {
      type: "stdio",
      command: "uvx",
      args: ["mcp-server-postgres", process.env.DATABASE_URL!],
    },
  },
});

#Configuring servers

Pass mcpServers on Agent as a record keyed by server name. Each entry is either an McpStdioServerConfig (spawn a child process and talk over stdio) or an McpHttpServerConfig (connect to a remote server over Streamable HTTP). The shape mirrors the Claude Agent SDK’s mcpServers option so existing configs port across without translation.

#Stdio servers

Stdio is the default transport. The server is spawned as a child process; JSON-RPC flows over its stdin/stdout. Child stderr is inherited so the server’s diagnostics appear on your console and a chatty server can never fill an unread pipe and block.

Three idiomatic stdio launchers — Python via uvx, Node via npx, and a local script — look like this:

mcpServers: {
  // Python MCP server pulled and run by uvx
  postgres: {
    command: "uvx",
    args: ["mcp-server-postgres"],
    env: { DATABASE_URL: process.env.DATABASE_URL! },
  },
  // Node MCP server, downloaded on demand by npx
  filesystem: {
    type: "stdio",
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/srv/data"],
  },
  // Your own local MCP server, run by an interpreter you control
  internal: {
    command: "/usr/bin/python3",
    args: ["./tools/mcp_server.py"],
  },
},

#HTTP servers

HTTP is Streamable HTTP — the modern MCP transport that multiplexes JSON-RPC over a single HTTP connection. Use it for hosted MCP servers or anything running outside your process.

mcpServers: {
  docs: {
    type: "http",
    url: "https://mcp.example.com/v1",
    headers: {
      Authorization: `Bearer ${process.env.MCP_TOKEN!}`,
      "X-Tenant": "acme",
    },
  },
},

#Choosing a transport

Two questions decide it: where does the server run, and who owns its credentials?

#Multiple servers

Configure as many servers as you want — they connect in parallel and their tools merge into the same registry. The config keys become the namespace prefix, so duplicate tool names across servers never collide.

import { Agent } from "@skawld/agent-sdk";

const agent = new Agent({
  provider,
  model: "claude-opus-4-5",
  mcpServers: {
    postgres: {
      command: "uvx",
      args: ["mcp-server-postgres"],
      env: { DATABASE_URL: process.env.DATABASE_URL! },
    },
    github: {
      type: "http",
      url: "https://mcp.github.com",
      headers: { Authorization: `Bearer ${process.env.GITHUB_TOKEN!}` },
    },
  },
});

#Connection lifecycle

MCP servers do not connect when you construct the Agent. They connect lazily on the first agent.session() call and the connect attempt is memoized — concurrent session() calls share one in-flight attempt rather than racing.

On agent.close() every client is closed; stdio child processes are terminated. close() is idempotent.

Per-call errors after a successful connect are handled differently: a tool invocation that throws is captured and returned as a tool result with is_error: true, so the model sees the failure and can react rather than crashing the run.

#Tool naming

Every MCP tool is registered under the fully-qualified name mcp__<server>__<tool>. The server segment is your config key; the tool segment is the name the MCP server reports in its own manifest. The fixed mcp__ prefix guarantees MCP tools never collide with skawld built-ins (Read, Bash, etc.).

Both segments are normalised: any character outside [a-zA-Z0-9_-] is replaced with a single underscore. So a config key of my server.v2 becomes my_server_v2 and a tool named fetch:url becomes fetch_url.

#Permissions

MCP tools flow through the same permission engine as every other tool, matched by their fully-qualified name. To allow or deny a specific MCP tool, use the mcp__<server>__<tool> form in a ToolRule. See Permissions for rule semantics and the canUseTool callback.

const agent = new Agent({
  provider,
  model: "claude-opus-4-5",
  mcpServers: {
    postgres: { command: "uvx", args: ["mcp-server-postgres"] },
  },
  permissions: {
    rules: [
      // Pre-approve read-only queries
      { kind: "tool", tool: "mcp__postgres__query", decision: "allow" },
      // Block the destructive one outright
      { kind: "tool", tool: "mcp__postgres__exec", decision: "deny" },
    ],
  },
});

#How MCP tools behave

Each MCP tool is wrapped as a skawld Tool at connect time. The wrapper preserves the server’s name, description, and JSON input schema verbatim — the MCP server owns its own validation, so skawld only checks that input is an object and passes it through.