npm package: @inception-agents/mcp
Description: MCP (Model Context Protocol) server SDK for Inception Agents — 99% reliable Claude-native tool calling
Latest version: 0.1.0

# @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

```bash
npm install @inception-agents/mcp
```

## Quick Start

```typescript
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`:

```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.

```typescript
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.

```typescript
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](https://www.inceptionagents.com/docs/integrations/mcp)
- [@inception-agents/core](https://www.npmjs.com/package/@inception-agents/core)