> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mcp integration

# MCP integration

The Model Context Protocol (MCP) is an open standard for exposing tools to LLMs. The SDK can bridge any MCP server so its tools become A2A capabilities on your agent — every MCP tool turns into a normal Svantic capability, with the same dashboard, telemetry, and caller experience.

This guide covers the everyday pattern. For the underlying class, see [`McpBridge`](../reference/mcp-bridge).

## Register an MCP server as capabilities

```typescript theme={null}
import { Agent } from '@svantic/sdk';

const agent = new Agent({
  name: 'browser-agent',
  description: 'Drives the browser.',
  mesh: {
    client_id: process.env.SVANTIC_CLIENT_ID!,
    client_secret: process.env.SVANTIC_CLIENT_SECRET!,
  },
});

await agent.register_mcp('chrome-devtools', {
  command: 'npx',
  args: ['chrome-devtools-mcp@latest'],
});

await agent.start();
```

For each tool the MCP server advertises, the SDK creates a capability named `<prefix>_<tool_name>` (hyphens in the prefix become underscores). So `chrome-devtools` + a tool called `navigate` becomes capability `chrome_devtools_navigate`.

**Register MCP servers before `start()` / `expose()`** so their tools appear on the agent card.

## Override the prefix

```typescript theme={null}
await agent.register_mcp('chrome-devtools', config, { tool_prefix: 'browser' });
// Tools now named browser_<tool_name>.
```

## Combine MCP tools with hand-written capabilities

They coexist. A `register_mcp` call adds to the existing capability set; `define_capability` can be called before or after.

```typescript theme={null}
await agent.register_mcp('filesystem', fs_config);
agent.define_capability({ name: 'summarize', /* … */ });
await agent.start();
```

## Shipping MCP configs with the SDK

For common MCP servers the SDK ships small config factories so you don't repeat the `command`/`args` boilerplate:

```typescript theme={null}
import { FilesystemToolServer, CodeRunnerToolServer } from '@svantic/sdk';

const fs_tool = new FilesystemToolServer({ root: '/data' });
await agent.register_mcp('filesystem', fs_tool.config());

const runner = new CodeRunnerToolServer({
  root: '/sandbox',
  allowed_commands: ['python', 'node'],
  timeout_ms: 10_000,
});
await agent.register_mcp('code-runner', runner.config());
```

See [Built-in tools](../reference/builtin-tools) for every helper.

## Environment and credentials

MCP servers usually pick up credentials from env vars. Pass them through:

```typescript theme={null}
await agent.register_mcp('github', {
  command: 'npx',
  args: ['@modelcontextprotocol/server-github'],
  env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN! },
});
```

## Lifecycle

* The MCP server runs as a child of your agent process.
* `agent.stop()` and `agent.close()` terminate every MCP bridge.
* If the MCP server crashes, its capabilities start failing — the caller sees a clear error and your telemetry shows a tool-level failure span.

## Directly driving an MCP server

Rarely needed, but supported — use [`McpBridge`](../reference/mcp-bridge) directly when you want to call an MCP tool from your own code without surfacing it as an agent capability.

```typescript theme={null}
import { McpBridge } from '@svantic/sdk';

const bridge = new McpBridge('filesystem');
await bridge.connect({ command: 'npx', args: ['@modelcontextprotocol/server-filesystem', '/data'] });
const result = await bridge.call_tool('read_file', { path: '/data/note.md' });
await bridge.close();
```

## See also

* [`agent.register_mcp`](../reference/agent#register_mcpserver_name-config-options)
* [`McpBridge`](../reference/mcp-bridge)
* [Built-in tools](../reference/builtin-tools)