API Reference

Complete reference for the Agents and MCPs API.

Core Types

Message

Represents a message in conversation:

interface Message {
  id: string;
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp: number;
  metadata?: Record<string, any>;
}

Agent

Configuration for an AI agent:

interface AgentConfig {
  name: string;
  systemPrompt: string;
  model?: string;
  temperature?: number;
  maxTokens?: number;
  tools?: Tool[];
  memory?: MemoryConfig;
}

Tool

Definition of a tool available to agents:

interface Tool {
  name: string;
  description: string;
  parameters: {
    type: 'object';
    properties: Record<string, Property>;
    required: string[];
  };
  handler: (params: any) => Promise<any>;
}

ToolCall

Represents tool invocation:

interface ToolCall {
  id: string;
  toolName: string;
  parameters: Record<string, any>;
  status: 'pending' | 'completed' | 'failed';
  result?: any;
  error?: string;
}

Agent API

useAgent Hook

Use an agent in your React component:

const {
  agent,
  messages,
  isLoading,
  send,
  reset,
  status
} = useAgent(config);

Parameters:

config: AgentConfig - Agent configuration

Returns:

agent: Agent - The agent instance
messages: Message[] - Conversation history
isLoading: boolean - Currently processing
send: (content: string) => Promise<void> - Send message
reset: () => void - Clear conversation
status: 'idle' | 'thinking' | 'calling-tool' - Agent status

send()

Send a message to the agent:

await send('What is the weather today?');

reset()

Clear conversation history:

reset();

MCP Server API

MCPServer

Create an MCP server:

const server = new MCPServer({
  name: string;
  version: string;
  tools: Tool[];
  authentication?: AuthConfig;
  options?: ServerOptions;
});

await server.start({ port: 8000 });

server.registerTool()

Add a tool dynamically:

server.registerTool({
  name: 'my_tool',
  description: 'Does something',
  parameters: {...},
  handler: async (params) => {...}
});

server.deregisterTool()

Remove a tool:

server.deregisterTool('my_tool');

MCP Client API

MCPClient

Connect to an MCP server:

const client = new MCPClient('http://localhost:8000');

client.getTools()

Get available tools:

const tools = await client.getTools();
// Returns: Tool[]

client.callTool()

Invoke a tool:

const result = await client.callTool(toolName, parameters);

client.callToolStream()

Stream tool response:

const stream = await client.callToolStream(toolName, parameters);
for await (const chunk of stream) {
  console.log(chunk);
}

Error Handling

MCPError

Standard error type:

class MCPError extends Error {
  code: string;
  statusCode: number;
  details?: any;
}

Common Error Codes:

TOOL_NOT_FOUND (404)
INVALID_PARAMETERS (400)
AUTHENTICATION_FAILED (401)
AUTHORIZATION_FAILED (403)
TOOL_TIMEOUT (504)
INTERNAL_ERROR (500)

Error Handling Example

try {
  await client.callTool('get_data', params);
} catch (error) {
  if (error instanceof MCPError) {
    switch (error.code) {
      case 'TOOL_NOT_FOUND':
        console.error('Tool not available');
        break;
      case 'INVALID_PARAMETERS':
        console.error('Invalid parameters:', error.details);
        break;
      default:
        console.error('Error:', error.message);
    }
  }
}

Memory Management

MemoryConfig

Configure agent memory:

interface MemoryConfig {
  type: 'none' | 'short-term' | 'long-term' | 'hybrid';
  maxMessages?: number;
  ttl?: number; // Time to live in ms
  persistent?: boolean;
}

Memory Types

none: No memory
short-term: Keep recent messages (default)
long-term: Persistent across sessions
hybrid: Combine short and long-term

Events

Agent Events

agent.on('message', (message: Message) => {});
agent.on('tool-call', (toolCall: ToolCall) => {});
agent.on('tool-result', (result: any) => {});
agent.on('error', (error: Error) => {});
agent.on('complete', () => {});

Streaming

Streaming Responses

const stream = agent.sendStream(message);

stream.on('data', (chunk) => {
  console.log('Partial response:', chunk);
});

stream.on('end', () => {
  console.log('Response complete');
});

Rate Limiting

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Pagination

List Operations

const options = {
  limit: 20,
  offset: 0,
  sortBy: 'created_at',
  sortOrder: 'desc'
};

const results = await client.listTools(options);
// Returns: { items: Tool[], total: number, hasMore: boolean }

Versioning

API versions in URL:

/api/v1/agent/...
/api/v2/agent/...

Changelog

v1.0.0

Initial release
Basic agent functionality
MCP server support
Tool integration

Support

For API issues or questions, refer to Examples & Use Cases or check MCPs Overview.