@inception-agents/mcp

MCP (Model Context Protocol) server SDK for Inception Agents. Auto-discovers intents from a tenant's /.well-known/agent-capabilities.json and registers them as Claude-callable tools. Achieves 99% reliability versus 60-80% for visual Computer-Using Agent (CUA) approaches, at 10-100x faster execution.

Installation

npm install @inception-agents/mcp

Quick Start

import { createMcpServer } from '@inception-agents/mcp';

const server = createMcpServer({
  tenantId: 'your-tenant-id',
  apiKey: process.env.IA_API_KEY!,
  domain: 'yoursite.com',
});

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

Claude Desktop Configuration

Add the server to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "yoursite": {
      "command": "node",
      "args": ["path/to/your/mcp-server.js"],
      "env": {
        "IA_API_KEY": "iak_your_api_key"
      }
    }
  }
}

API Reference

createMcpServer(config)

Creates an MCP server that auto-discovers intents from the tenant's capabilities manifest and exposes them as tools.

const server = createMcpServer({
  tenantId: 'your-tenant-id',
  apiKey: process.env.IA_API_KEY!,
  domain: 'yoursite.com',
  debug: true,
});

Returns: McpServer

McpServer Methods

| Method | Signature | Description | |--------|-----------|-------------| | start | (options: { port: number; hostname?: string }) => Promise<void> | Start the HTTP server | | stop | () => Promise<void> | Stop the server and clean up timers | | getTools | () => McpTool[] | Get the list of registered tools | | refresh | () => Promise<void> | Re-fetch the capabilities manifest and update tools | | handleRequest | (request: McpRequest) => Promise<McpResponse> | Handle a raw MCP request (for custom transports) |

buildToolsFromManifest(manifest)

Converts a capabilities manifest into MCP tool definitions. Each intent in the manifest becomes a tool with typed parameters derived from the form schema.

import { buildToolsFromManifest } from '@inception-agents/mcp';

const tools = buildToolsFromManifest(manifest);
// Intent "free_trial" → tool "create_free_trial"
// Intent "enterprise_quote" → tool "request_enterprise_quote"
// Intent "checkout" → tool "complete_checkout"

Returns: McpTool[]

Configuration

McpServerConfig

| Option | Type | Default | Description | |--------|------|---------|-------------| | tenantId | string | required | Inception Agents tenant ID | | apiKey | string | required | Inception Agents API key | | domain | string | required | Tenant's domain (for manifest discovery) | | apiUrl | string | https://api.inceptionagents.com | API base URL | | refreshInterval | number | 300000 (5 min) | Manifest refresh interval in milliseconds | | debug | boolean | false | Enable debug logging |

How It Works

1. Discovery -- The server fetches https://{domain}/.well-known/agent-capabilities.json to discover available intents
2. Tool Registration -- Each intent is converted to an MCP tool with typed input schemas derived from the form fields
3. Tool Execution -- When Claude calls a tool, the server validates inputs, POSTs to the tenant's express flow endpoint, and returns the result
4. Interaction Logging -- Every tool execution is logged as an interaction_mode: 'mcp' event with verification_status: 'verified' (fully billable)
5. Auto-Refresh -- The capabilities manifest is periodically re-fetched to pick up new intents without server restart

Why MCP over CUA

| | MCP | Visual CUA | |---|-----|-----------| | Reliability | 99% | 60-80% | | Speed | 1-2 seconds | 30-120 seconds | | Identifiability | Every interaction tracked | Partial visibility | | Billing | Fully verified | Requires heuristics |

Exported Types

• McpServerConfig — Server configuration interface
• McpServer — Server instance with start/stop/refresh methods
• McpTool — Tool definition with name, description, and input schema
• ToolResult — Tool execution result

Related

• Full documentation
• @inception-agents/core