MCP Server

Give AI coding assistants direct access to the Backbone platform — manage projects, 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 Backbone MCP Server exposes the entire Backbone API as MCP tools, so your AI-powered IDE can:

Create and manage projects and schemas
Run data extractions and test schemas
Convert documents and transcribe audio
Query AI models through the LLM Gateway
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 @manfred-kunze-dev/backbone-mcp-server

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

Setup

Get an API key

Head to the API Keys page in the sidebar and create a new key. Copy it — you'll need it for the configuration below.

Dedicated key

Create a separate API key for your MCP server so you can rotate or revoke it independently.

Configure your IDE

Add the Backbone MCP server to your IDE's MCP configuration. See the IDE-specific sections below.

IDE Configuration

Claude Code

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

{
  "mcpServers": {
    "backbone": {
      "command": "npx",
      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
      "env": {
        "BACKBONE_API_KEY": "sk_your_api_key"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "backbone": {
      "command": "npx",
      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
      "env": {
        "BACKBONE_API_KEY": "sk_your_api_key"
      }
    }
  }
}

Windsurf

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

{
  "mcpServers": {
    "backbone": {
      "command": "npx",
      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
      "env": {
        "BACKBONE_API_KEY": "sk_your_api_key"
      }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "backbone": {
      "command": "npx",
      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
      "env": {
        "BACKBONE_API_KEY": "sk_your_api_key"
      }
    }
  }
}

Works with any MCP client

The Backbone MCP Server uses the standard MCP protocol. Any MCP-compatible client — including VS Code extensions, custom agents, and other tools — can connect using the same configuration pattern.

Environment Variables

Variable	Required	Default	Description
`BACKBONE_API_KEY`	Yes	—	API key for authenticating with the Backbone backend
`BACKBONE_BASE_URL`	No	`https://backbone.manfred-kunze.dev/api`	Base URL of the Backbone backend. Override for self-hosted instances
`MCP_TRANSPORT`	No	`stdio`	Transport mode: `stdio` or `http`
`MCP_HTTP_PORT`	No	`3100`	Port for the HTTP transport (only used when `MCP_TRANSPORT=http`)

Available Tools

Projects

Manage projects within your organization.

Tool	Description
`backbone_list_projects`	List projects with optional search and pagination
`backbone_get_project`	Get a project by ID
`backbone_create_project`	Create a new project
`backbone_update_project`	Update a project
`backbone_delete_project`	Delete a project and all its data

Schemas

Define extraction schemas within projects.

Tool	Description
`backbone_list_schemas`	List schemas in a project
`backbone_get_schema`	Get a schema by ID
`backbone_create_schema`	Create a new schema
`backbone_update_schema`	Update a schema
`backbone_delete_schema`	Delete a schema and all its versions

Schema Versions

Manage versioned snapshots of schema definitions.

Tool	Description
`backbone_create_schema_version`	Create a new version (becomes active)
`backbone_list_schema_versions`	List all versions of a schema
`backbone_get_schema_version`	Get a specific version
`backbone_get_latest_schema_version`	Get the latest active version
`backbone_activate_schema_version`	Re-activate a historical version

Schema Testing

Validate schemas and test extractions without persisting data.

Tool	Description
`backbone_validate_schema`	Validate a JSON Schema definition
`backbone_test_schema`	Test a schema against sample text with AI extraction

Extractions

Extract structured data from text using schemas and AI models.

Tool	Description
`backbone_create_extraction`	Extract data from text (sync or async)
`backbone_get_extraction`	Get an extraction by ID
`backbone_list_extractions`	List extractions with filtering
`backbone_estimate_tokens`	Estimate token usage without executing
`backbone_rerun_extraction`	Re-run an existing extraction

Document Conversion

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

Tool	Description
`backbone_convert_document`	Convert documents from URLs, base64, or local files
`backbone_get_task_status`	Check status of an async conversion task
`backbone_get_task_result`	Get the result of a completed conversion

Audio Transcription

Transcribe audio files using AI models.

Tool	Description
`backbone_transcribe_audio`	Transcribe an audio file (supports flac, mp3, mp4, ogg, wav, webm)

AI Gateway

Access multiple AI providers through a unified interface.

Tool	Description
`backbone_chat`	Send a chat completion request
`backbone_list_models`	List available AI models and providers

API Documentation

Browse the backend's OpenAPI documentation by section.

Tool	Description
`backbone_list_api_doc_sections`	List available doc sections with endpoint counts
`backbone_get_api_docs`	Fetch filtered docs for a specific section

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

When to use HTTP

HTTP transport is useful when you want a single shared MCP server instance for your team, or when integrating with web-based MCP clients. For individual IDE use, stick with stdio.