MCP (Model Context Protocol)

Model Context Protocol (MCP) is an open standard developed by Anthropic for connecting AI agents to external tools, data sources, and services. Think of it as a universal adapter layer: instead of writing a custom integration for every API or service, you connect to an MCP server that already exposes that service's capabilities as tools. The agent then calls those tools just like any other — with no knowledge of the underlying transport.

How It Works

MCP separates concerns cleanly into three parts:

• MCP servers — lightweight processes (local or remote) that expose a set of named tools. A server can wrap anything: a filesystem, a database, a REST API, a browser, a SaaS product.
• MCP clients — connect to servers, discover their tools, and call them on behalf of an agent. MCPClient is agention-lib's client implementation.
• Tools — once discovered, MCP tools become standard agention-lib Tool instances. The agent doesn't know or care whether a tool comes from MCP or custom code.

This means the entire ecosystem of existing MCP servers — filesystem, git, Slack, GitHub, databases, web search, and more — is immediately available to any agention-lib agent, without writing any integration code.

Agent  ──→  MCPClient  ──→  MCP Server  ──→  External Service
              (Tool[])        (stdio / HTTP)

Installation

Install the MCP SDK alongside agention-lib:

npm install @modelcontextprotocol/sdk

Quick Start

import { MCPClient, ClaudeAgent } from '@agentionai/agents';

// 1. Connect to an MCP server
const mcp = MCPClient.fromStdio({
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
});

await mcp.connect();

// 2. Pass its tools to any agent
const agent = new ClaudeAgent({
  id: 'file-agent',
  name: 'File Agent',
  description: 'An agent that can work with files.',
  apiKey: process.env.ANTHROPIC_API_KEY!,
  tools: mcp.getTools(),
});

const result = await agent.execute('List the files in /tmp');

// 3. Clean up when done
await mcp.disconnect();

Transport Types

Stdio — Local Process

Use MCPClient.fromStdio() to spawn a local MCP server as a child process. Communication happens over stdin/stdout.

const mcp = MCPClient.fromStdio({
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/home/user/docs'],
  env: { MY_VAR: 'value' }, // optional environment variables
});

This is the most common pattern for development and tools like filesystem, git, databases, etc.

HTTP — Remote Server

Use MCPClient.fromUrl() to connect to a remote MCP server over Streamable HTTP.

const mcp = MCPClient.fromUrl('https://my-mcp-server.com/mcp');

Authentication

API Key / Bearer Token

Pass static auth headers for API-key protected servers:

const mcp = MCPClient.fromUrl('https://my-mcp-server.com/mcp', {
  headers: {
    Authorization: `Bearer ${process.env.MCP_API_KEY}`,
  },
});

OAuth 2.0

For servers that use OAuth, implement the OAuthClientProvider interface from the MCP SDK and pass it as authProvider:

import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';

// Your OAuth provider implementation
const myOAuthProvider: OAuthClientProvider = {
  // ... implement the interface
};

const mcp = MCPClient.fromUrl('https://my-mcp-server.com/mcp', {
  authProvider: myOAuthProvider,
});

Lifecycle

MCPClient follows an explicit connect/disconnect lifecycle:

const mcp = MCPClient.fromStdio({ command: 'node', args: ['server.js'] });

// Connect — discovers all tools from the server
await mcp.connect();

// Use tools with any agent
const tools = mcp.getTools();

// Disconnect — stops the process / closes the HTTP session
await mcp.disconnect();

Both connect() and disconnect() are idempotent — safe to call multiple times.

getTools() returns an empty array before connect() is called.

Using Tools

getTools() returns standard Tool instances that work with all agent types:

const tools = mcp.getTools();

// Pass at construction time
const agent = new ClaudeAgent({ ..., tools });

// Or add dynamically
agent.addTools(mcp.getTools());

Tools from multiple MCP servers can be combined freely:

const fsMcp = MCPClient.fromStdio({ command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'] });
const dbMcp = MCPClient.fromUrl('https://my-db-mcp.com/mcp');

await Promise.all([fsMcp.connect(), dbMcp.connect()]);

const agent = new ClaudeAgent({
  ...,
  tools: [...fsMcp.getTools(), ...dbMcp.getTools()],
});

API Reference

MCPClient.fromStdio(config, options?)

Creates a client that spawns a local process.

Parameter	Type	Description
config.command	string	Command to run (e.g. "npx", "node", "python")
config.args	string[]	Arguments passed to the command
config.env	Record<string, string>	Environment variables for the process
options.clientName	string	Client name sent during handshake (default: "agention-mcp-client")
options.clientVersion	string	Client version (default: "1.0.0")

MCPClient.fromUrl(url, options?)

Creates a client that connects over HTTP.

Parameter	Type	Description
url	string	Full URL to the MCP endpoint
options.headers	Record<string, string>	Static HTTP headers (e.g. Authorization)
options.authProvider	OAuthClientProvider	OAuth provider for dynamic authorization
options.clientName	string	Client name sent during handshake
options.clientVersion	string	Client version

mcp.connect()

Connects to the server and fetches all available tools. Idempotent.

mcp.getTools()

Returns Tool[] — one instance per tool exposed by the MCP server. Returns [] before connect().

mcp.disconnect()

Disconnects from the server and clears the tool list. Idempotent.