MCP API Reference

This document provides a complete API reference for AG-Kit’s Model Context Protocol (MCP) integration components.

Core Classes

AGKitMCPServer

Exposes AG-Kit tools as a standard MCP server.

Constructor

new AGKitMCPServer(config: AGKitMCPServerConfig)

Parameters:

config: AGKitMCPServerConfig - Server configuration object

AGKitMCPServerConfig Interface:

interface AGKitMCPServerConfig {
  name: string;                    // Server name
  version: string;                 // Server version
  description?: string;            // Optional server description
  enableLogging?: boolean;         // Enable debug logging (default: true)
  includeMetadata?: boolean;       // Include execution metadata (default: true)
  errorHandling?: 'throw' | 'return_error'; // Error handling strategy (default: 'return_error')
  transformInput?: (input: any) => any;     // Input transformation function
  transformOutput?: (output: any) => any;   // Output transformation function
}

Methods

`registerTool()`

registerTool(tool: BaseTool, toolConfig?: MCPToolConfig): MCPToolMetadata

Parameters:

tool: BaseTool - The AG-Kit tool to register
toolConfig?: MCPToolConfig - Optional tool configuration

Returns: MCPToolMetadata - Metadata for the registered tool MCPToolConfig Interface:

interface MCPToolConfig {
  name?: string;        // Override tool name
  description?: string; // Override tool description
  namePrefix?: string;  // Add prefix to tool name
}

registerTools()

registerTools(tools: BaseTool[], toolConfig?: MCPToolConfig): MCPToolMetadata[]

Parameters:

tools: BaseTool[] - Array of AG-Kit tools to register
toolConfig?: MCPToolConfig - Optional shared configuration

Returns: MCPToolMetadata[] - Array of metadata for registered tools

unregisterTool()

Remove a tool from the server.

unregisterTool(name: string): boolean

Parameters:

name: string - Name of the tool to remove

Returns: boolean - True if tool was removed, false if not found

run()

Start the MCP server with specified transport.

run(transportConfig: MCPTransportConfig): Promise<void>

Parameters:

transportConfig: MCPTransportConfig - Transport configuration

MCPTransportConfig Types:

type MCPTransportConfig = {
  type: 'stdio';
} | {
  type: 'memory';
  memoryId?: string;
} | {
  type: 'sse';
  sseSetup: SSETransportSetup;
} | {
  type: 'streamableHttp';
  streamableHttpSetup: StreamableHTTPTransportSetup;
}

stop()

Stop the MCP server and cleanup resources.

stop(): Promise<void>

callTool()

Execute a registered tool directly.

callTool(name: string, args: Record<string, any>): Promise<CallToolResult>

Parameters:

name: string - Name of the tool to execute
args: Record<string, any> - Tool arguments

Returns: Promise<CallToolResult> - MCP-formatted tool result

listTools()

Get list of all registered tools.

listTools(): Array<{name: string; description: string; inputSchema: any}>

Returns: Array of tool metadata objects

isServerRunning()

Check if the server is currently running.

isServerRunning(): boolean

Returns: boolean - True if server is running

getStats()

Get server statistics and information.

getStats(): {
  totalTools: number;
  toolNames: string[];
  toolTypes: Record<string, number>;
  isRunning: boolean;
  serverInfo: {
    name: string;
    version: string;
    description?: string;
  };
}

addEventListener()

Add event listener for server events.

addEventListener(listener: MCPEventListener): void

Parameters:

listener: MCPEventListener - Event listener function

removeEventListener()

Remove event listener.

removeEventListener(listener: MCPEventListener): boolean

Parameters:

listener: MCPEventListener - Event listener to remove

Returns: boolean - True if listener was removed

MCPClientManager

Manages connections to external MCP servers.

Constructor

new MCPClientManager()

Methods

addServer()

Add and connect to an MCP server.

addServer(
  serverId: string, 
  config: MCPClientConfig, 
  connectionOptions?: MCPConnectionOptions
): Promise<void>

Parameters:

serverId: string - Unique identifier for the server
config: MCPClientConfig - Client configuration
connectionOptions?: MCPConnectionOptions - Optional connection settings

MCPClientConfig Interface:

interface MCPClientConfig {
  name: string;
  version: string;
  transport?: MCPTransportConfig;  // Required if client not provided
  client?: Client;                 // Pre-connected client
  onReconnectNeeded?: (serverId: string, config: MCPClientConfig) => Promise<Client>;
  capabilities?: {
    experimental?: Record<string, any>;
    sampling?: Record<string, any>;
  };
}

MCPConnectionOptions Interface:

interface MCPConnectionOptions {
  autoReconnect?: boolean;         // Enable auto-reconnection (default: true)
  reconnectDelay?: number;         // Delay between reconnect attempts (default: 5000ms)
  maxReconnectAttempts?: number;   // Maximum reconnect attempts (default: 3)
  heartbeatInterval?: number;      // Heartbeat interval (default: 30000ms)
}

disconnectServer()

Disconnect from a specific server.

disconnectServer(serverId: string): Promise<void>

disconnectAll()

Disconnect from all servers.

disconnectAll(): Promise<void>

createClientTools()

Create AG-Kit tool wrappers for all available MCP tools.

createClientTools(serverId?: string): MCPClientTool[]

Parameters:

serverId?: string - Optional server ID to filter tools

Returns: MCPClientTool[] - Array of wrapped tools

createClientTool()

Create a specific AG-Kit tool wrapper for an MCP tool.

createClientTool(
  serverId: string, 
  toolName: string, 
  agKitToolName?: string
): MCPClientTool

Parameters:

serverId: string - Server ID containing the tool
toolName: string - Name of the MCP tool
agKitToolName?: string - Custom name for the AG-Kit tool

Returns: MCPClientTool - Wrapped tool instance

callTool()

Call an MCP tool directly.

callTool(serverId: string, toolName: string, args: any): Promise<any>

isServerConnected()

Check if a server is connected.

isServerConnected(serverId: string): boolean

getStats()

Get client manager statistics.

getStats(): {
  connectedServers: number;
  totalTools: number;
  serverStatus: Record<string, boolean>;
}

addEventListener()

Add event listener for client events.

addEventListener(listener: MCPEventListener): void

removeEventListener()

Remove event listener.

removeEventListener(listener: MCPEventListener): boolean

MCPClientTool

Wraps an external MCP tool to work within AG-Kit’s tool system.

Constructor

new MCPClientTool(
  mcpClient: Client,
  mcpToolMetadata: MCPToolMetadata,
  config?: MCPToolConfig,
  adapterConfig?: MCPAdapterConfig
)

Parameters:

mcpClient: Client - MCP client instance
mcpToolMetadata: MCPToolMetadata - Tool metadata from MCP server
config?: MCPToolConfig - Optional tool configuration
adapterConfig?: MCPAdapterConfig - Optional adapter configuration

MCPToolMetadata Interface:

interface MCPToolMetadata {
  name: string;
  description?: string;
  inputSchema?: any;  // MCP JSON schema
}

MCPAdapterConfig Interface:

interface MCPAdapterConfig {
  includeMetadata?: boolean;                    // Include execution metadata
  transformInput?: (input: any) => any;        // Transform input before MCP call
  transformOutput?: (output: any) => any;      // Transform output after MCP call
  errorHandler?: (error: Error) => ToolResult; // Custom error handler
}

Methods

invoke()

Execute the MCP tool (inherited from BaseTool).

invoke(input: any, context?: ToolExecutionContext): Promise<ToolResult>

getMCPMetadata()

Get the original MCP tool metadata.

getMCPMetadata(): MCPToolMetadata

isConnected()

Check if the underlying MCP client is connected.

isConnected(): boolean

updateConfig()

Update tool configuration.

updateConfig(newConfig: Partial<MCPToolConfig>): void

updateAdapterConfig()

Update adapter configuration.

updateAdapterConfig(newAdapterConfig: Partial<MCPAdapterConfig>): void

MCPToolkit

High-level toolkit for managing MCP tools from external servers.

Constructor

new MCPToolkit(name?: string)

Parameters:

name?: string - Optional toolkit name (default: “mcp-toolkit”)

Methods

addServer()

Add an MCP server and load its tools.

addServer(serverId: string, config: MCPClientConfig): Promise<void>

removeServer()

Remove a server and its tools.

removeServer(serverId: string): Promise<void>

getConnectedServers()

Get list of connected server IDs.

getConnectedServers(): string[]

getServerTools()

Get tools from a specific server.

getServerTools(serverId: string): MCPClientTool[]

refresh()

Refresh all server connections and reload tools.

refresh(): Promise<void>

cleanup()

Cleanup all resources and disconnect from servers.

cleanup(): Promise<void>

getClientManager()

Get the underlying client manager.

getClientManager(): MCPClientManager

getStats()

Get toolkit statistics.

getStats(): {
  name: string;
  description?: string;
  toolCount: number;
  mcp: {
    connectedServers: number;
    totalTools: number;
    serverStatus: Record<string, boolean>;
  };
}

Utility Functions

zodSchemaToMCPSchema()

Convert a Zod schema to MCP JSON schema format.

function zodSchemaToMCPSchema(zodSchema: z.ZodSchema<any>): any

Parameters:

zodSchema: z.ZodSchema<any> - Zod schema to convert

Returns: MCP-compatible JSON schema object

convertAGKitToolToMCPMetadata()

Convert AG-Kit BaseTool to MCP tool metadata.

function convertAGKitToolToMCPMetadata(
  tool: BaseTool,
  config?: AGKitMCPServerConfig,
  toolConfig?: MCPToolConfig
): MCPToolMetadata

createAGKitMCPServer()

Utility function to create and configure an MCP server.

async function createAGKitMCPServer(
  config: AGKitMCPServerConfig,
  tools?: BaseTool[]
): Promise<AGKitMCPServer>

createMCPToolkit()

Create a new MCP toolkit with pre-configured servers.

type MCPServersConfig =
  | Record<string, MCPClientConfig>
  | Array<{ id: string; config: MCPClientConfig }>;

async function createMCPToolkit(
  servers: MCPServersConfig,
  name?: string
): Promise<MCPToolkit>

Parameters:

servers - Server configurations in object mapping (recommended) or array format
name - Optional toolkit name

Examples:

// Object mapping format (recommended)
const toolkit = await createMCPToolkit({
  time: {
    command: "uvx",
    args: ["mcp-server-time"]
  },
  weather: {
    url: "http://localhost:3000/mcp"
  }
});

// Object mapping with full MCPClientConfig (if you need custom name/version)
const toolkit2 = await createMCPToolkit({
  time: {
    name: "custom-time-server",
    version: "2.0.0",
    transport: {
      command: "uvx",
      args: ["mcp-server-time"]
    }
  }
});

// Array format (backward compatible)
const toolkit3 = await createMCPToolkit([
  { 
    id: "time", 
    config: { 
      transport: { 
        command: "uvx", 
        args: ["mcp-server-time"] 
      } 
    } 
  }
]);

Memory Transport Registry

MemoryTransportRegistry

Singleton registry for managing in-memory MCP transports.

Methods

getInstance()

Get the singleton instance.

static getInstance(): MemoryTransportRegistry

registerServer()

registerServer(memoryId: string, server: AGKitMCPServer): void

unregisterServer()

Unregister a server.

unregisterServer(memoryId: string): void

getServer()

Get a registered server.

getServer(memoryId: string): AGKitMCPServer | undefined

createTransportPair()

Create a linked pair of memory transports.

createTransportPair(memoryId: string): {server: any; client: any}

getClientTransport()

Get client transport for connections.

getClientTransport(memoryId: string): any

callTool()

Direct tool call via memory transport.

async callTool(
  memoryId: string, 
  toolName: string, 
  args: Record<string, any>
): Promise<CallToolResult>

listTools()

List tools via memory transport.

async listTools(memoryId: string): Promise<Array<{
  name: string; 
  description: string; 
  inputSchema: any;
}>>

Type Definitions

MCPEvent

Union type for all MCP events.

type MCPEvent =
  | { type: 'connected'; clientName: string }
  | { type: 'disconnected'; clientName: string; reason?: string }
  | { type: 'tool_discovered'; tool: MCPToolMetadata }
  | { type: 'tool_called'; toolName: string; arguments: any }
  | { type: 'tool_result'; toolName: string; result: CallToolResult }
  | { type: 'error'; error: Error; context?: string }

MCPEventListener

Event listener function type.

type MCPEventListener = (event: MCPEvent) => void

MCPClientStatus

Status information for MCP client connections.

interface MCPClientStatus {
  connected: boolean;
  sessionId?: string;
  serverInfo?: {
    name: string;
    version: string;
  };
  capabilities?: Record<string, any>;
  toolCount: number;
  resourceCount: number;
  promptCount: number;
  lastActivity?: Date;
  reconnectAttempts?: number;
  errors: Array<{
    timestamp: Date;
    error: Error;
    context?: string;
  }>;
}

Transport Configuration Types

Note: The type field is optional in all transport configurations. If not specified, the type will be auto-detected based on the configuration properties with the following priority: memory > stdio > streamableHttp > sse.

MCPStdioTransportConfig

interface MCPStdioTransportConfig {
  type?: 'stdio';  // Optional, auto-detected if command is present
  command: string;
  args?: string[];
  timeout?: number;
}

Example:

// Type is optional
const config = {
  command: "uvx",
  args: ["mcp-server-time"]
};

MCPSSETransportConfig

interface MCPSSETransportConfig {
  type?: 'sse';  // Optional, auto-detected for URL-based configs
  url: string;
  timeout?: number;
}

MCPStreamableHTTPTransportConfig

interface MCPStreamableHTTPTransportConfig {
  type?: 'streamableHttp';  // Optional, auto-detected for URL-based configs (default)
  url: string;
  timeout?: number;
}

Example:

// Type is optional, will auto-detect as streamableHttp
const config = {
  url: "https://agkit.mintlify.app/mcp"
};

MCPInMemoryTransportConfig

interface MCPInMemoryTransportConfig {
  type?: 'memory';  // Optional, auto-detected if memoryId is present
  memoryId: string;
  timeout?: number;
}

Example:

// Type is optional
const config = {
  memoryId: "my-server"
};

MCPCustomTransportConfig

interface MCPCustomTransportConfig {
  type?: 'custom';  // Optional, auto-detected if transport is present
  transport: any;  // User-provided transport instance
  timeout?: number;
}

Auto-Detection Priority

When type is not specified, the transport type is detected in the following order:

memory - If memoryId is present
stdio - If command is present
streamableHttp - If url is present (default for URL-based configs)
sse - Requires explicit type: 'sse' for URL-based configs
custom - If transport is present

Error Handling

McpError

MCP protocol error class.

class McpError extends Error {
  constructor(public code: number, message: string);
}

Error Codes

enum ErrorCode {
  ParseError = -32700,
  InvalidRequest = -32600,
  MethodNotFound = -32601,
  InvalidParams = -32602,
  InternalError = -32603
}

Constants and Exports

Module Exports

// Core classes
export { AGKitMCPServer, MCPClientManager, MCPClientTool, MCPToolkit }

// Utility functions
export { 
  zodSchemaToMCPSchema, 
  convertAGKitToolToMCPMetadata,
  createAGKitMCPServer,
  createMCPToolkit
}

// Memory transport
export { MemoryTransportRegistry, memoryTransportRegistry }

// Types
export type {
  AGKitMCPServerConfig,
  MCPClientConfig,
  MCPToolConfig,
  MCPAdapterConfig,
  MCPConnectionOptions,
  MCPToolMetadata,
  MCPEvent,
  MCPEventListener,
  MCPClientStatus,
  MCPTransportConfig,
  // ... all transport config types
}

Global Registry

// Global memory transport registry instance
export const memoryTransportRegistry: MemoryTransportRegistry

Usage Patterns

Server Pattern

import { AGKitMCPServer } from '@ag-kit/tools/mcp';

const server = new AGKitMCPServer(config);
server.registerTool(tool);
await server.run(transportConfig);

Client Pattern

import { MCPClientManager } from '@ag-kit/tools/mcp';

const manager = new MCPClientManager();
await manager.addServer(serverId, clientConfig);
const tools = manager.createClientTools();

Toolkit Pattern

import { MCPToolkit } from '@ag-kit/tools/mcp';

const toolkit = new MCPToolkit();
await toolkit.addServer(serverId, config);
const tools = toolkit.getTools();

This API reference provides complete documentation for all public interfaces and methods in AG-Kit’s MCP integration. For usage examples and implementation patterns, see the MCP Integration Guide and MCP Examples.

TypeScript SDK

Python SDK

Headless UI Components

CLI Tools

​MCP API Reference

​Core Classes

​AGKitMCPServer

​Constructor

​Methods

registerTool()

registerTools()

unregisterTool()

run()

stop()

callTool()

listTools()

isServerRunning()

getStats()

addEventListener()

removeEventListener()

​MCPClientManager

​Constructor

​Methods

addServer()

disconnectServer()

disconnectAll()

createClientTools()

createClientTool()

callTool()

isServerConnected()

getStats()

addEventListener()

removeEventListener()

​MCPClientTool

​Constructor

​Methods

invoke()

getMCPMetadata()

isConnected()

updateConfig()

updateAdapterConfig()

​MCPToolkit

​Constructor

​Methods

addServer()

removeServer()

getConnectedServers()

getServerTools()

refresh()

cleanup()

getClientManager()

getStats()

​Utility Functions

​zodSchemaToMCPSchema()

​convertAGKitToolToMCPMetadata()

​createAGKitMCPServer()

​createMCPToolkit()

​Memory Transport Registry

​MemoryTransportRegistry

​Methods

getInstance()

registerServer()

unregisterServer()

getServer()

createTransportPair()

getClientTransport()

callTool()

listTools()

​Type Definitions

​MCPEvent

​MCPEventListener

​MCPClientStatus

​Transport Configuration Types

​MCPStdioTransportConfig

​MCPSSETransportConfig

​MCPStreamableHTTPTransportConfig

​MCPInMemoryTransportConfig

​MCPCustomTransportConfig

​Auto-Detection Priority

​Error Handling

MCP API Reference

Core Classes

AGKitMCPServer

Constructor

Methods

`registerTool()`

MCPClientManager

Constructor

Methods

MCPClientTool

Constructor

Methods

MCPToolkit

Constructor

Methods

Utility Functions

zodSchemaToMCPSchema()

convertAGKitToolToMCPMetadata()

createAGKitMCPServer()

createMCPToolkit()

Memory Transport Registry

MemoryTransportRegistry

Methods

Type Definitions

MCPEvent

MCPEventListener

MCPClientStatus

Transport Configuration Types

MCPStdioTransportConfig

MCPSSETransportConfig

MCPStreamableHTTPTransportConfig

MCPInMemoryTransportConfig

MCPCustomTransportConfig

Auto-Detection Priority

Error Handling

McpError

Error Codes

Constants and Exports

Module Exports

Global Registry

Usage Patterns

Server Pattern

Client Pattern

Toolkit Pattern