Skip to main content

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.

​
McpBridge

import { McpBridge } from '@svantic/sdk';

​
What it is

McpBridge is the SDK’s client for a Model Context Protocol (MCP) server. It spawns the server as a child process, performs the MCP handshake, discovers the tools it advertises, and lets you invoke them by name. The normal path for agents is agent.register_mcp() — it wraps McpBridge and turns every MCP tool into an A2A capability automatically. You import McpBridge yourself only when you want to use MCP tools without publishing them.

​
When to use it

Reach for McpBridge directly when:
  • You’re writing a script or utility that needs to call a single MCP tool once.
  • You want to inspect an MCP server’s tool list without registering it with Svantic.
  • You’re building custom glue (e.g. forwarding MCP results to somewhere other than an agent capability).
For the mainline case — “make these MCP tools callable as agent capabilities” — use agent.register_mcp().

​
Functional usage

import { McpBridge } from '@svantic/sdk';

// 1. Create the bridge with a label (used in logs and errors).
const bridge = new McpBridge('filesystem');

// 2. Spawn the MCP server and handshake.
await bridge.connect({
  command: 'npx',
  args: ['@modelcontextprotocol/server-filesystem', '/data'],
});

// 3. Introspect what's available.
const tools = await bridge.list_tools();
console.log(tools.map((t) => t.name));

// 4. Call a tool directly. Arguments match the MCP server's JSON Schema.
const result = await bridge.call_tool('read_file', {
  path: '/data/notes/today.md',
});

// 5. Always close — otherwise the child process leaks until GC.
await bridge.close();
See the MCP integration guide for the normal agent-side pattern.

​
Types

​
McpServerSpawnConfig

interface McpServerSpawnConfig {
  command: string;
  args?: string[];
  env?: Record<string, string>;
}
What to execute. For stdio-based MCP servers that ship on npm, the usual shape is: 
{ command: 'npx', args: ['@modelcontextprotocol/server-filesystem', '/path'] }

​
McpToolDescriptor

interface McpToolDescriptor {
  name: string;
  description?: string;
  input_schema: Record<string, unknown>;
}
Returned by list_tools(). input_schema is the raw JSON Schema the MCP server advertised.

​
Constructor

new McpBridge(server_name: string)
server_name is a logical label (e.g. 'chrome-devtools'). Used for error messages and telemetry.

​
Methods

​
connect(config)

await bridge.connect({ command: 'npx', args: ['chrome-devtools-mcp@latest'] });
Spawn the MCP server and perform the MCP handshake. Idempotent — calling connect() on an already-connected bridge is a no-op.

​
list_tools()

Return the set of tools the MCP server advertised. Throws when not connected.

​
call_tool(tool_name, args)

Invoke a tool by name. Throws when not connected, when the tool rejects, or when the MCP server returns an error result.

​
close()

Shut down the child process and release resources. Idempotent.

​
Properties

PropertyTypeDescription
connectedbooleantrue while the child process is alive.
server_namestringThe label passed to the constructor.
spawn_configMcpServerSpawnConfig | nullThe config that was passed to connect(), or null before connect.

​
Example

const bridge = new McpBridge('filesystem');

await bridge.connect({
  command: 'npx',
  args: ['@modelcontextprotocol/server-filesystem', '/data'],
});

const tools = await bridge.list_tools();
const result = await bridge.call_tool('read_file', { path: '/data/note.md' });

await bridge.close();