MCP Server Mode

Any agent built with the SDK can be exposed as an MCP (Model Context Protocol) server. This enables other agents, tools, and platforms to discover and invoke your agent through a standardized protocol — regardless of what SDK or language they use.

Why MCP Server Mode?

MCP Client mode (connecting to MCP servers for tools) lets your agent use external tools. MCP Server mode does the reverse — it lets your agent be a tool for other agents.

Traditional: Your Agent → calls → MCP Server (tools)
Server Mode: Other Agents → call → Your Agent (as MCP server)

This unlocks:

Multi-agent orchestration without tight coupling
Language-agnostic integration — a Python agent can call your TypeScript agent
Platform integration — any MCP-compatible platform can use your agent
Microservices for AI — deploy specialized agents as independent services

Quick Start

import { Agent, createAgentMCPServer } from 'assistme-agent-sdk'
import { claude } from 'assistme-agent-sdk-provider-claude'

const researcher = new Agent({
  name: 'researcher',
  model: claude('claude-sonnet-4-6'),
  instructions: 'Research topics thoroughly using web search.',
  tools: [webSearch, readUrl],
})

// Expose as an MCP server
const server = createAgentMCPServer(researcher, {
  name: 'research-agent',
  description: 'A research agent that can search the web and summarize findings',
  transport: 'stdio', // or 'sse'
})

await server.start()

This creates an MCP server with two tools:

research_agent — Start a new conversation with the researcher
research_agent_reply — Continue an existing conversation

Consuming an Agent MCP Server

From another agent or any MCP client:

import { MCPToolProvider } from 'assistme-agent-sdk/mcp'

const researchAgent = await MCPToolProvider.connect({
  transport: 'stdio',
  command: 'node',
  args: ['./research-agent-server.js'],
})

const orchestrator = new Agent({
  name: 'orchestrator',
  model: claude('claude-sonnet-4-6'),
  instructions: 'You coordinate multiple specialized agents.',
  tools: [
    ...researchAgent.tools(),
    ...codeAgent.tools(),
    ...designAgent.tools(),
  ],
})

Transport Options

stdio (Local)

Best for same-machine communication:

const server = createAgentMCPServer(agent, {
  transport: 'stdio',
})

SSE (Network)

Best for remote/distributed agents:

const server = createAgentMCPServer(agent, {
  transport: 'sse',
  port: 3001,
  cors: { origin: '*' },
  auth: {
    type: 'bearer',
    validate: async (token) => {
      return await verifyToken(token)
    },
  },
})

Multi-Agent Architecture

Build a team of specialized agents, each running as an MCP server:

// research-server.ts
const server = createAgentMCPServer(researchAgent, {
  name: 'research',
  transport: 'sse',
  port: 3001,
})

// code-server.ts
const server = createAgentMCPServer(codeAgent, {
  name: 'code',
  transport: 'sse',
  port: 3002,
})

// orchestrator.ts — connects to all agents
const research = await MCPToolProvider.connect({ transport: 'sse', url: 'http://localhost:3001' })
const code = await MCPToolProvider.connect({ transport: 'sse', url: 'http://localhost:3002' })

const orchestrator = new Agent({
  name: 'orchestrator',
  model: claude('claude-sonnet-4-6'),
  instructions: `You are a project manager. You have access to:
- A research agent for information gathering
- A code agent for writing and reviewing code
Break down tasks and delegate to the right specialist.`,
  tools: [...research.tools(), ...code.tools()],
})

Custom MCP Tools

Add additional MCP tools alongside the agent conversation tools:

import { Tool } from 'assistme-agent-sdk'
import { z } from 'zod'

const server = createAgentMCPServer(agent, {
  name: 'assistant',
  transport: 'stdio',
  additionalTools: [
    Tool.create({
      name: 'get_status',
      description: 'Get the agent server status',
      parameters: z.object({}),
      execute: async () => ({
        uptime: process.uptime(),
        activeSessions: sessionStore.count(),
        version: '1.0.0',
      }),
    }),
  ],
})

Session Management in MCP Server Mode

The server automatically manages sessions per MCP client:

const server = createAgentMCPServer(agent, {
  name: 'assistant',
  transport: 'sse',
  sessions: {
    store: SessionStore.redis({ url: 'redis://localhost:6379' }),
    ttl: '1h',         // Sessions expire after 1 hour of inactivity
    maxConcurrent: 100, // Max 100 concurrent sessions
  },
})

MCP clients interact through two tools:

assistant — Starts a new session and sends the first message
assistant_reply — Sends a follow-up message to an existing session

In-Process MCP Server

For testing or single-process multi-agent setups, create an in-process MCP server:

import { createInProcessMCPServer } from 'assistme-agent-sdk'

const researchServer = createInProcessMCPServer(researchAgent)
const codeServer = createInProcessMCPServer(codeAgent)

const orchestrator = new Agent({
  name: 'orchestrator',
  model: claude('claude-sonnet-4-6'),
  instructions: 'Coordinate research and code agents.',
  tools: [
    ...researchServer.tools(),
    ...codeServer.tools(),
  ],
})

// No network, no serialization — direct function calls
const result = await Runner.run(orchestrator, { messages })

Docker Deployment

Deploy agent MCP servers as containers:

FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 3001
CMD ["node", "server.js"]

# docker-compose.yml
services:
  research-agent:
    build: ./agents/research
    ports: ["3001:3001"]
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

  code-agent:
    build: ./agents/code
    ports: ["3002:3002"]
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

  orchestrator:
    build: ./agents/orchestrator
    ports: ["3000:3000"]
    depends_on: [research-agent, code-agent]
    environment:
      - RESEARCH_AGENT_URL=http://research-agent:3001
      - CODE_AGENT_URL=http://code-agent:3002

Best Practices

Start with in-process, move to network — Use createInProcessMCPServer during development, switch to SSE transport for production deployment.
Add authentication for network servers — Always use bearer token auth for SSE-based agent servers exposed on a network.
Set session TTLs — Idle sessions consume memory. Set appropriate TTLs and max concurrent limits.
Name your servers clearly — The server name becomes the MCP tool name. Choose descriptive names.
Document tool descriptions — Other agents choose your agent based on its tool description. Make it clear and specific.
Use health checks — For containerized deployments, add a health check endpoint to detect and restart unhealthy agent servers.

MCP Server Mode

On this page