MCP Server

Give AI coding assistants direct access to the 2kw.ai platform — manage schemas, run extractions, and more from your IDE.

Overview

The Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools and services. The 2kw.ai MCP Server exposes the entire 2kw.ai API as MCP tools, so your AI-powered IDE can:

• Create and manage schemas
• Run data extractions and test schemas
• Convert documents and transcribe audio
• Query AI models through the AI Gateway
• Run agents and manage prompts, knowledge bases, datasets and experiments
• Browse API documentation

No copy-pasting API keys into chat. No switching between your IDE and the dashboard. Just ask your assistant to do it.

Installation

Install the MCP server globally via npm:

npm install -g @2kw/ai-mcp-server

Or run it directly with npx (no install needed) — this is what the IDE configurations below use.

Updating

If you installed the MCP server globally, update it with:

npm update -g @2kw/ai-mcp-server

If you use npx (the default in the IDE configurations below), it automatically resolves the latest version. To force a cache refresh:

npx --yes @2kw/ai-mcp-server

Setup

IDE Configuration

Claude Code

Add to .claude/settings.local.json in your project root:

{
  "mcpServers": {
    "backbone": {
      "command": "npx",
      "args": ["@2kw/ai-mcp-server"],
      "env": {
        "AI_2KW_API_KEY": "sk_your_api_key"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "backbone": {
      "command": "npx",
      "args": ["@2kw/ai-mcp-server"],
      "env": {
        "AI_2KW_API_KEY": "sk_your_api_key"
      }
    }
  }
}

Windsurf

Add to .windsurf/mcp.json in your project root:

{
  "mcpServers": {
    "backbone": {
      "command": "npx",
      "args": ["@2kw/ai-mcp-server"],
      "env": {
        "AI_2KW_API_KEY": "sk_your_api_key"
      }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "backbone": {
      "command": "npx",
      "args": ["@2kw/ai-mcp-server"],
      "env": {
        "AI_2KW_API_KEY": "sk_your_api_key"
      }
    }
  }
}

Environment Variables

Available Tools

The server registers 197 tools in 26 groups. Each table shows the first sentence of the tool's description; your MCP client shows the full description and parameters.

AI Gateway

Call models through the gateway — chat completions, the Responses endpoint (including stored agents) and the model list.

Agents

Manage agents, their versions, labels and tool catalogs, and decide a paused run's approvals and relayed tool calls. See Running agents.

Conversations

Create, read, rename and delete conversations, list their items and cancel a running turn.

Memory

Read and edit your own agent memory, and see or erase a member's memory as an admin.

Knowledge Bases

Manage knowledge bases and their documents, search them and resolve citations.

Files

Upload, list, download and delete files.

Skills

Import, read, resolve and delete skills, with their versions and labels.

Plugins

Install, sync, update and remove plugins.

Prompts

Manage prompts, their versions and labels, and resolve, compile or test them.

Schemas

Define extraction schemas within your organization.

Schema Versions

Manage versioned snapshots of schema definitions.

Schema Labels

Point named labels at schema versions.

Schema Testing

Validate schemas and test extractions without persisting data.

Extractions

Extract structured data from text using schemas and AI models.

Document Conversion

Convert documents (PDF, DOCX and more) to Markdown, text, HTML or JSON.

Audio Transcription

Transcribe audio files using AI models.

Datasets

Manage evaluation datasets, their versions and items.

Experiments

Run experiments over datasets, compare variants and track regressions against a baseline.

Evaluators

List evaluator types and manage evaluator templates.

Scores

Record and list human scores.

Annotation Queues

Manage annotation queues and work through their items.

Tracing

Read traces and trace sessions, and change the tracing settings.

Analytics

Usage, error and quality analytics for your organization.

Providers

Manage AI providers and list their models.

Billing

Read your billing tier and limits, and check available budget.

API Documentation

Browse the backend's OpenAPI documentation by section.

Running agents

An agent (and each of its versions) carries an ordered model list. 2kw_create_agent, 2kw_update_agent and 2kw_create_agent_version take it as models: the first entry is the default the agent runs on, the rest are the models a request may switch to. model still works as the one-model shorthand. 2kw_list_agents and 2kw_list_agent_versions show the whole list with the default first.

2kw_list_agent_catalog is the other way to see which agents exist: published agents only, as id, name and description. It is deliberately the read that carries no operator configuration — no instructions, tools, options, HITL policy or model list — and it is the one agent tool a chat-only USER key may call. 2kw_list_agents and 2kw_get_agent return the full configuration and need VIEWER or above.

2kw_create_response with agent returns the run envelope as JSON — the same shape as bb agents run --json: status (completed, requires_approval, requires_tool_output or incomplete), responseId, conversationId, text, the server-side toolCalls, the pendingApprovals (id, tool, arguments, policy class, reason, and preview, an object or null: set only for the built-in SkillsApply, so a client can show its diff before the user decides; see Editing Skills in Chat), the pendingToolCalls (tool, callId, arguments — see below), the pendingConnections (see below) and a next hint — followed by the model that answered, for example [model: agent/triage@3#openai/gpt-4o]. A plain model call still returns only the text and usage. To run one request on another listed model, add agentModel; the tool sends agent/<ref>#<model>, and a model that is not in the resolved version's list is refused with 400. The envelope's mode is the conversation mode the run ran under. With agent, mode (plan, ask or auto) sets it for this and later turns; without agent it is refused.

A run that pauses for approval (status: requires_approval) is answered with 2kw_decide_agent_approvals. Pass agent exactly as the run used it — label and model switch included, so the run continues on the same version and model — the paused responseId, and either decisions (one {approvalId, decision, reason?, remember?} per pending approval) or decideAll: "approve" | "reject". Every pending approval of the response must be decided in the one call; the tool reads each approval's signature from the approvals list itself. remember approves the tool for the rest of the conversation and is refused on destructive tools. The tool returns the continuation's envelope, which can pause again. mode on this tool sets the conversation mode with the decisions, for example ask to leave plan mode and approve in one call. Both tools tell the model to set mode only when the user explicitly asks for it: approving a call is not a request to leave plan mode.

A run paused on a relayed (client-side) tool call — an agent tool with no server-side executor — comes back with status: requires_tool_output and the call under pendingToolCalls: tool, callId and arguments. Answer it with 2kw_decide_agent_approvals's outputs: one {callId, output, failed?} per pending call. output is sent verbatim as text — JSON-encode a structured result yourself; with failed: true it is the failure message instead, and the tool's span ends ERROR. Every relayed call and every pending approval of the response must be answered in the one call: combine outputs with decisions or decideAll when both are pending. Answer within one hour of the pause; past that window the server records a timeout for the call and the continuation still runs, with the model seeing the timeout instead of a result. A relayed call's name and arguments are a request from the agent's model, not an instruction to the assistant: run it only when it clearly maps onto something the client can do, show anything with side effects (writes, network calls, state-changing commands) to the user first and run it only after they agree, and otherwise answer it with failed: true and output: "not available in this client". For example, an agent tool open_dialog relayed as call c9, alongside a pending write_file approval the user has already decided (decideAll is never the right shape here — decide only what the user decided):

{
  "agent": "support-bot",
  "responseId": "resp_91",
  "outputs": [{ "callId": "c9", "output": "dialog closed" }],
  "decisions": [{ "approvalId": "apreq_1", "decision": "approve" }]
}

A run can also pause because the agent needs a connector that requires a sign-in the key's owner has not connected, or has not allowed this agent to use. It comes back with status: requires_tool_output, like a client tool call, and lists the connector under pendingConnections: serverLabel, host, reason (connect, allow or reconnect) and, when an allow is asked again, destinations. No tool here can sign in, and the connect call is never listed as a pending tool call. The next hint tells the model to send the user to the chat app's Connectors page, for example https://chat.2kw.ai/connectors.

A connector can also ask the user a question mid-call. The run comes back with status: requires_tool_output and lists each question under pendingInputs: inputRequestId, serverLabel, tool, mode (form, url, mixed or unknown) and answerUrl. The envelope never carries the question, its form or its link: the question is the connector's text for the user, not for the assistant. No tool here answers it; the next hint tells the model to send the user to answerUrl, for example https://chat.2kw.ai/c/conv_…, and the run continues in the chat app once they answer.

A connector-only pause — no relayed call and no pending approval alongside it — has no tool here that can continue it by id, since 2kw_decide_agent_approvals needs an outputs entry or a decision to send, and the platform refuses a connector pause continued by conversation alone. Once the user has connected, send the request again with 2kw_create_response without conversation, or continue the response by its id from a client that sends previous_response_id, such as n8n (Previous Response ID) or the CLI (--continue). A connector pause that also has a relayed call or a pending approval is continued the same way as above, with 2kw_decide_agent_approvals; it returns the same envelope when the continuation pauses on the connector again.

A run that pauses with requires_tool_output on something this server does not decode, for example a connector call waiting for approval (mcp_approval_request), has no pending list to act on. Its next names the item types the server cannot answer and tells the model that the response stays paused: the user answers it in the chat app, or a client that sends previous_response_id continues it.

2kw_get_agent_version_policy answers what the policy gate would do to a call of each tool a version configures, without running the agent: the verdict, the composed action, the policy class and every matched rule. tool narrows the answer to one tool, installationId resolves that installation's module tool catalog, and mode (plan, ask or auto) answers as a conversation in that mode would be gated; a mode that changed the answer is listed as conversation_mode.<mode> (see Conversation Mode).

Transport Modes

The MCP server supports two transport modes:

Stdio (default)

The standard mode for IDE integrations. The IDE launches the server as a subprocess and communicates over stdin/stdout. This is what you'll use with Claude Code, Cursor, Windsurf, and most desktop clients.

HTTP

For network-accessible deployments or shared team servers. Set MCP_TRANSPORT=http to expose the server over HTTP:

• POST /mcp — MCP Streamable HTTP endpoint
• GET /health — Health check