Full MCP support -- connect to external MCP servers to use their tools, or expose Cogitator tools as an MCP server.

Overview

The @cogitator-ai/mcp package provides bidirectional MCP integration:

MCPClient -- connect to any MCP server (filesystem, database, GitHub, etc.) and use its tools inside Cogitator agents.
MCPServer -- expose your Cogitator tools, resources, and prompts as an MCP server for Claude Desktop, other AI assistants, or any MCP client.
Tool Adapter -- convert between Cogitator and MCP tool formats, including Zod-to-JSON Schema conversion.

pnpm add @cogitator-ai/mcp @cogitator-ai/core

MCPClient

Connecting to an MCP Server

Use MCPClient.connect() to establish a connection. The client discovers server capabilities automatically and provides access to tools, resources, and prompts.

import { MCPClient } from '@cogitator-ai/mcp';

const client = await MCPClient.connect({
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@anthropic/mcp-server-filesystem', '/home/user/documents'],
  timeout: 10000,
});

console.log(client.getCapabilities());

const tools = await client.getTools();
const resources = await client.listResources();
const prompts = await client.listPrompts();

await client.close();

Using MCP Tools with Agents

The tools returned by getTools() are standard Cogitator Tool instances -- pass them directly to an agent:

import { Cogitator, Agent } from '@cogitator-ai/core';
import { MCPClient } from '@cogitator-ai/mcp';

const fsClient = await MCPClient.connect({
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@anthropic/mcp-server-filesystem', '/workspace'],
});

const dbClient = await MCPClient.connect({
  transport: 'http',
  url: 'http://localhost:3001/mcp',
});

const fsTools = await fsClient.getTools();
const dbTools = await dbClient.getTools();

const agent = new Agent({
  name: 'file-manager',
  model: 'openai/gpt-4o',
  instructions: 'Help users manage files and query databases.',
  tools: [...fsTools, ...dbTools],
});

const cog = new Cogitator({
  /* ... */
});
const result = await cog.run(agent, {
  input: 'List all .ts files in /workspace/src and count them',
});

await fsClient.close();
await dbClient.close();

connectMCPServer Helper

For the common pattern of connect-get-tools-cleanup, use the shorthand:

import { connectMCPServer } from '@cogitator-ai/mcp';

const { tools, cleanup } = await connectMCPServer({
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@anthropic/mcp-server-github'],
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
});

const agent = new Agent({
  name: 'github-bot',
  model: 'openai/gpt-4o',
  tools,
});

await cleanup();

MCPClientConfig

Option	Type	Description
`transport`	`'stdio' \| 'http' \| 'sse'`	Transport protocol
`command`	`string`	Command for stdio transport
`args`	`string[]`	Command arguments for stdio
`env`	`Record<string, string>`	Environment variables for stdio
`url`	`string`	Server URL for HTTP/SSE transport
`timeout`	`number`	Connection timeout in ms
`clientName`	`string`	Client identification name
`clientVersion`	`string`	Client version string
`retry`	`MCPRetryConfig`	Retry settings for failed operations
`autoReconnect`	`boolean`	Auto-reconnect on connection loss (default: true)

Retry and Reconnection

The client has built-in retry with exponential backoff for all operations. On connection loss, it automatically reconnects:

const client = await MCPClient.connect({
  transport: 'http',
  url: 'http://mcp-server:3000/mcp',
  retry: {
    maxRetries: 5,
    initialDelay: 1000,
    maxDelay: 30000,
    backoffMultiplier: 2,
    retryOnConnectionLoss: true,
  },
  onReconnecting: (attempt) => console.log(`Reconnecting (attempt ${attempt})...`),
  onReconnected: () => console.log('Reconnected'),
  onReconnectFailed: (err) => console.error('Reconnection failed:', err),
});

Resources and Prompts

Beyond tools, MCP servers can expose resources (data sources) and prompts (reusable prompt templates):

const resources = await client.listResources();

const content = await client.readResource('file:///workspace/config.json');
console.log(content.text);

const prompts = await client.listPrompts();

const messages = await client.getPrompt('code-review', {
  language: 'typescript',
  style: 'thorough',
});

MCPServer

Exposing Cogitator Tools

Create an MCP server to make your Cogitator tools available to any MCP client:

import { MCPServer } from '@cogitator-ai/mcp';
import { tool } from '@cogitator-ai/core';
import { z } from 'zod';

const calculator = tool({
  name: 'calculate',
  description: 'Evaluate a math expression',
  parameters: z.object({ expression: z.string() }),
  execute: async ({ expression }) => eval(expression),
});

const server = new MCPServer({
  name: 'my-tools',
  version: '1.0.0',
  transport: 'stdio',
});

server.registerTools([calculator]);
await server.start();

HTTP Transport

For remote access, use the HTTP transport:

const server = new MCPServer({
  name: 'remote-tools',
  version: '1.0.0',
  transport: 'http',
  port: 3000,
  host: 'localhost',
  logging: true,
});

server.registerTools([calculator, webSearch, fileReader]);
await server.start();

Clients connect to http://localhost:3000/mcp.

Registering Resources

Expose data sources as MCP resources:

server.registerResource({
  uri: 'config://app/settings',
  name: 'App Settings',
  description: 'Current application configuration',
  mimeType: 'application/json',
  read: async () => ({
    uri: 'config://app/settings',
    text: JSON.stringify(await loadAppSettings()),
  }),
});

server.registerResource({
  uri: 'db://users/{userId}',
  name: 'User Profile',
  description: 'Fetch a user profile by ID',
  read: async (params) => ({
    uri: `db://users/${params.userId}`,
    text: JSON.stringify(await db.getUser(params.userId)),
  }),
});

Registering Prompts

Expose reusable prompt templates:

server.registerPrompt({
  name: 'code-review',
  title: 'Code Review',
  description: 'Generate a code review for the given language',
  arguments: [
    { name: 'language', description: 'Programming language', required: true },
    { name: 'style', description: 'Review depth: quick or thorough' },
  ],
  get: async (args) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Review this ${args.language} code. Style: ${args.style ?? 'thorough'}.`,
        },
      },
    ],
  }),
});

Tool Adapter

Convert tools between Cogitator and MCP formats manually when you need fine-grained control.

Cogitator to MCP

import { cogitatorToMCP } from '@cogitator-ai/mcp';

const mcpDef = cogitatorToMCP(calculator);

MCP to Cogitator

import { mcpToCogitator, wrapMCPTools } from '@cogitator-ai/mcp';

const cogTool = mcpToCogitator(mcpToolDefinition, client, {
  namePrefix: 'github_',
  descriptionTransform: (desc) => `[GitHub] ${desc}`,
});

const allTools = await wrapMCPTools(client, { namePrefix: 'fs_' });

Schema Conversion

The adapter includes utilities for converting between Zod schemas and JSON Schema, which is useful when working with MCP's JSON Schema-based tool definitions:

import { zodToJsonSchema, jsonSchemaToZod } from '@cogitator-ai/mcp';
import { z } from 'zod';

const schema = z.object({
  query: z.string().describe('Search query'),
  limit: z.number().int().min(1).max(100).optional(),
});

const jsonSchema = zodToJsonSchema(schema);

const zodSchema = jsonSchemaToZod({
  type: 'object',
  properties: {
    query: { type: 'string', description: 'Search query' },
    limit: { type: 'integer', minimum: 1, maximum: 100 },
  },
  required: ['query'],
});

Claude Desktop Integration

To use your Cogitator tools in Claude Desktop, run an MCP server with stdio transport and add it to your Claude config:

claude_desktop_config.json

{
  "mcpServers": {
    "my-cogitator-tools": {
      "command": "node",
      "args": ["./dist/mcp-server.js"]
    }
  }
}

mcp-server.ts

import { MCPServer } from '@cogitator-ai/mcp';
import { calculator, webSearch } from './tools';

const server = new MCPServer({
  name: 'my-cogitator-tools',
  version: '1.0.0',
  transport: 'stdio',
});

server.registerTools([calculator, webSearch]);
await server.start();

Model Context Protocol (MCP)