06. Model Context Protocol (MCP) Integration

⭐️ Love Smoke Monkey Harness? Please support the project with a star on GitHub! 🌐 Interactive Simulator: Test the agent loop and stream live at smoke-monkey-harness.vercel.app

The Model Context Protocol (MCP) is an open standard that allows AI agents to securely connect to external data sources, tools, and environments.

Smoke Monkey provides a dual MCP integration:

1. The Native MCP Client inside @smoke-monkey/harness connects external tools (GitHub, databases, browsers) into your agent loop.
2. The @smoke-monkey/mcp Server exposes 22 development tools to external agents (Claude Code, Cursor, Codex, Windsurf) to scaffold and verify harness projects.

1. Using External MCP Tools in Your Agent

You can connect external MCP servers directly to your agent via options.mcp. Both stdio (local processes) and streamable-HTTP (SSE endpoints) transports are supported:

import { createAgent } from '@smoke-monkey/harness';

const agent = createAgent({
  workspacePath: process.cwd(),
  mcp: [
    // 1. Local process via stdio
    {
      id: 'github',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-github'],
      env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
    },
    // 2. Local database inspector
    {
      id: 'db',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-postgres', 'postgresql://user:pass@localhost:5432/mydb'],
    },
    // 3. Remote cloud service via streamable-HTTP (SSE)
    {
      id: 'cloud-metrics',
      url: 'https://mcp.internal.company.com/sse',
      headers: { Authorization: `Bearer ${process.env.CLOUD_TOKEN}` },
    },
  ],
});

Automatic Tool Namespacing

To avoid tool collisions, external MCP tools are automatically namespaced using the server ID:

• GitHub tool create_issue becomes: github__create_issue
• Postgres tool query becomes: db__query

Lazy Server Startup

MCP servers are connected lazily. The harness does not launch background processes until the agent's phase machine or user explicitly requests a tool from that server, saving memory and startup latency.

2. Managing MCP Servers at Runtime

You can dynamically add or remove MCP servers after your agent has started:

// Dynamically register an external server
await agent.addMcpServer({
  id: 'slack',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-slack'],
  env: { SLACK_BOT_TOKEN: process.env.SLACK_TOKEN },
});

// List all registered servers and their status
const servers = agent.listMcpServers();
console.log('Active MCP servers:', servers);

// Remove a server
await agent.removeMcpServer('slack');

3. The @smoke-monkey/mcp Server

If you use external agent tools like Claude Code, Codex, Cursor, or Windsurf, you can give them native mastery over the Smoke Monkey Harness using @smoke-monkey/mcp.

Run via npx

npx -y @smoke-monkey/mcp

Configure in Your Client (mcpServers JSON)

Add this to your client's configuration file (e.g., ~/.claude/claude_desktop_config.json, ~/.cursor/mcp.json):

{
  "mcpServers": {
    "smoke-monkey": {
      "command": "npx",
      "args": ["-y", "@smoke-monkey/mcp"]
    }
  }
}

The 22 Development Tools in @smoke-monkey/mcp

The server provides 22 structured tools categorized into three primary areas:

1. Harness Workflow Tools

2. Category-Wise Skill Tools

3. Feature Deep-Dive Guides

Specialized guidance tools that require zero parameters:

• harness_guide_loop_phases_guards_and_compaction
• harness_guide_permissions_the_three_pauses
• harness_guide_tools_custom_tool_implementation
• harness_guide_subcontexts_activation_and_switching
• harness_guide_skills_skill_md_discovery
• harness_guide_mcp_servers_and_discovery
• harness_guide_providers_models_and_api_keys
• harness_guide_storage_sessions_runs_messages
• harness_guide_events_streaming_and_ui_wiring
• harness_guide_ui_bridge_and_components
• harness_guide_errors_validation_and_pauses

Next Steps

• Inject domain-specific engineering playbooks with skills: 07. Just-in-Time Skills
• Dynamically alter system prompts: 08. Sub-Contexts
• Render MCP tool cards in the chat UI: 10. React UI Components

MCP (Model Context Protocol)

⭐️ Love Smoke Monkey Harness? Please support the project with a star on GitHub! 🌐 Interactive Simulator: Test the agent loop and stream live at smoke-monkey-harness.vercel.app

The harness can surface external tools through the Model Context Protocol — stdio servers (command / args) or streamable-HTTP servers (url / headers).

Config

type McpServerConfig = {
  id: string;          // stable id, becomes the tool namespace
  name: string;
  description: string;
  icon?: string;
  command?: string;    // stdio: binary to spawn (e.g. 'npx')
  args?: string[];
  cwd?: string;
  env?: Record<string, string>;
  url?: string;        // streamable-HTTP transport
  headers?: Record<string, string>;
  enabled?: boolean;
};

Connecting

const agent = createAgent({
  provider: 'nvidia',
  model: 'nvidia/nemotron-3-super-120b-a12b',
  workspacePath: process.cwd(),
  mcp: [
    { id: 'github', name: 'GitHub', description: 'GitHub API',
      command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! } },
    { id: 'postgres', name: 'Postgres', description: 'Query a database',
      url: 'https://mcp.example.com/pg', headers: { Authorization: 'Bearer …' } },
  ],
});

Servers connect lazily when the matching mcp_<id> sub-context is activated. Their tools surface as <id>__<tool> — e.g. github__search_repos.

Approvals

MCP tools are read-only until approved. A disabled or unknown server raises a request_mcp_approval / mcp.approval_required pause:

agent.on('request_mcp_approval', async (e) => {
  // e.data: { toolCallId, configs/info }
  await agent.resolveMcpDecision(e.data.toolCallId, {
    action: 'enable',           // 'enable' | 'leave' | 'deny'
    names: ['github', 'postgres'],
  });
});

autoApprove: true enables servers without pausing.

Stock catalog

Curated server recipes ship with the library: listStockCategories(), findStockEntry(name), stockToMcpConfig(entry). Examples include GitHub, Postgres, Playwright, Sentry, database and browser entries. Recipes return a ready McpServerConfig you can hand straight back to options.mcp.

Runtime

agent.addMcpServer(cfg) / agent.removeMcpServer(id) / agent.listMcpServers() manage servers between runs. McpManager exposes the underlying lifecycle.

The agent plugin

plugin/ ships an MCP server that brings this library's build-agent and deep-feature guide content into Claude Code, Codex, opencode, Antigravity, and GitHub Copilot. Install with bash plugin/install.sh. Host layout and the strict portable manifest are documented in plugin/README.md. The offline fixture suite in scripts/fixtures/test-plugin-mcp.ts validates the manifests end-to-end.