Chordian MCP Server

Chordian MCP Server exposes Chordian workflows to any MCP client over Streamable HTTP. Tool handlers are thin; HTTP integration and validation live in app/services/ and app/schemas/.

A Model Context Protocol (MCP) server that exposes Chordian-style workflows to clients over Streamable HTTP. AI assistants like Claude and Cursor can call registered tools with your Chordian API key on the inbound x-api-key header.

Responses from most tools are JSON strings shaped like {"success": true, "data": ...} or {"success": false, "error": "..."}.

ℹ️ Tip: Chordian MCP is compatible with Cursor, Claude Desktop, Claude Code, OpenAI’s MCP tool runtime, and any other MCP-capable client.

Remote MCP Server

The easiest way to take advantage of Chordian MCP is by using the hosted remote URL. This provides a seamless experience without requiring local installation or configuration.

Simply use the remote MCP server URL with your Chordian API key:

https://mcp.chordian.ai/mcp

Setting	Value
Base URL	`https://mcp.chordian.ai`
MCP endpoint	`https://mcp.chordian.ai/mcp`
Health probe	`https://mcp.chordian.ai/health`
Transport	Streamable HTTP
Auth header	`x-api-key: <your-api-key>`

Get your Chordian API key from your Chordian workspace settings.

Connect to Cursor

To set up the Chordian MCP server in Cursor, add the configuration below to your mcp.json (Settings → MCP → Add new MCP server). Replace <api-key> with your Chordian API key.

{
  "mcpServers": {
    "Chordian-MCP-Server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.chordian.ai/mcp",
        "--header",
        "x-api-key: <api-key>"
      ]
    }
  }
}

ℹ️ Note: mcp-remote is a small bridge package that lets stdio-only clients talk to remote, HTTP-based MCP servers. It is invoked here through npx so no global install is required.

Connect to Claude Desktop

Open your claude_desktop_config.json and add the same configuration block:

# Create the config file if it doesn't exist
touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
 
# Open the config file in your editor
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

{
  "mcpServers": {
    "Chordian-MCP-Server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.chordian.ai/mcp",
        "--header",
        "x-api-key: <api-key>"
      ]
    }
  }
}

Restart Claude Desktop. The Chordian tools (e.g. start_workflow, start_people_search, start_research) will appear in the tools picker.

Connect to Claude Code

Claude Code natively supports remote MCP servers. Add Chordian with a single command:

claude mcp add Chordian-MCP-Server \
  --transport http https://mcp.chordian.ai/mcp \
  --header "x-api-key: <api-key>"

Or add it manually to your .claude/settings.json:

{
  "mcpServers": {
    "Chordian-MCP-Server": {
      "type": "http",
      "url": "https://mcp.chordian.ai/mcp",
      "headers": {
        "x-api-key": "<api-key>"
      }
    }
  }
}

OpenAI

OpenAI’s Responses API can call remote MCP servers as tools. Provide the Chordian endpoint and your API key in the headers block.

from openai import OpenAI
 
client = OpenAI()
 
resp = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "chordian",
            "server_url": "https://mcp.chordian.ai/mcp",
            "require_approval": "never",
            "headers": {
                "x-api-key": "<api-key>"
            },
        },
    ],
    input="Start a company search for Series B fintech startups in New York.",
)
 
print(resp.output_text)

Clients that don’t support remote MCPs

mcp-remote is a lightweight bridge that lets MCP clients which can only talk to local (stdio) servers connect to remote MCP servers over HTTP, forwarding custom headers (like x-api-key) for authentication. It serves as a stop-gap until popular MCP clients natively support remote, authorized servers.

{
  "mcpServers": {
    "Chordian-MCP-Server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.chordian.ai/mcp",
        "--header",
        "x-api-key: <api-key>"
      ]
    }
  }
}

Authentication

Every tool call that talks to the Chordian agent core or memory service reads the inbound MCP HTTP request and requires the x-api-key header.

x-api-key: <YOUR_API_KEY>

Internally, this key is:

Forwarded to the agent core as Authorization: Bearer <api-key> (company search, people search, research, and enterprise search tools).
Forwarded to the memory service as Authorization: Bearer <api-key> (all memory_* tools).

Missing or invalid keys produce a structured error:

{
  "success": false,
  "error": "Missing x-api-key header"
}

Response envelope

All Chordian MCP tools return a JSON string with a consistent shape so your client can branch on success before reading data.

{
  "success": true,
  "data": { }
}

{
  "success": false,
  "error": "string"
}

Field	Type	Description
`success`	boolean	`true` if the upstream request succeeded.
`data`	any	(success only) Raw JSON returned by the upstream service.
`error`	string	(failure only) Human-readable cause (validation message, auth error, or `"Internal server error"`).

Available Tools

Tool modules are imported from app/server.py and register on the shared FastMCP instance.

Area	Tools
Company search	`start_workflow`, `continue_workflow`, `get_status_workflows`, `stop`, `start_enrichment`, `stop_enrichment`, `get_lists`, `get_search_results`, `company_database_search`
People search	`start_people_search`, `continue_people_search`, `get_status_people_search`, `stop_people_search`, `people_database_search`
Research	`get_active_workflow`, `start_research`, `get_result_of_search`
Memory	`memory_list_departments`, `memory_get_department`, `memory_create_department`, `memory_upload_data`, `memory_ingest_connectors`, `memory_generate`, `memory_chat`
Enterprise search	`enterprise_send_chat_message`, `enterprise_get_chat_sessions`, `enterprise_create_chat_session`, `enterprise_rename_chat_session`, `enterprise_get_connector_status`, `enterprise_get_connectors`, `enterprise_create_connector`, `enterprise_get_cc_pair`, `enterprise_update_cc_pair_status`, `enterprise_connector_run_once`, `enterprise_create_deletion_attempt`, `enterprise_associate_credential`, `enterprise_upload_project_file`, `enterprise_upload_project_files`, `enterprise_get_project_file_statuses`

Optional US weather helpers (get_alerts, get_forecast, National Weather Service) exist in app/tools/weather.py but are not imported in server.py; add weather to the server imports if you want them exposed.

Company Search

Tool	Arguments	Purpose
`start_workflow`	`prompt: string`	Start a company-search workflow from a natural-language prompt.
`continue_workflow`	`thread_id: string`, `total_target: int (≥ 1)`	Extend an existing workflow to grow the target list.
`get_status_workflows`	`workflow_id: string`	Poll workflow state and partial results.
`stop`	`workflow_id: string`	Cancel a running company-search workflow.
`start_enrichment`	`thread_id`, `list_id`, `column_name`, `enrichment_type`, `instruction?`	Enrich a column on a list (e.g. add CEO emails).
`stop_enrichment`	`workflow_id: string`	Cancel a running enrichment job.
`get_lists`	(none)	List all company-search lists for the tenant.
`get_search_results`	`thread_id: string`	Fetch the rows produced by a thread.
`company_database_search`	Search payload	Fuzzy database search by field path (Atlas Search).

People Search

Tool	Arguments	Purpose
`start_people_search`	`prompt: string`	Start a people-search workflow from a natural-language prompt.
`continue_people_search`	`thread_id: string`, `total_target: int (≥ 1)`	Extend a people-search workflow to grow the target list.
`get_status_people_search`	`workflow_id: string`	Poll people-search state and partial results.
`stop_people_search`	`workflow_id: string`	Cancel a running people-search workflow.
`people_database_search`	Search payload	Fuzzy database search by field path (Atlas Search).

Research

Tool	Arguments	Purpose
`get_active_workflow`	(none)	List currently active research workflows.
`start_research`	`query`, `allow_clarification?`, `max_concurrent_research_units?`, `max_researcher_iterations?`	Start a deep research workflow with optional concurrency / iteration caps.
`get_result_of_search`	`research_id: string`	Fetch the final result for a research workflow.

Memory

Maps to Memory APIs (MEMORY_URL, default https://graph-kb.chordian.ai).

Tool	Purpose
`memory_list_departments`	List knowledge graph instances (departments/lists).
`memory_get_department`	Get a graph by `graph_id`.
`memory_create_department`	Create a new department graph.
`memory_upload_data`	Upload CSV or other files into a graph.
`memory_ingest_connectors`	Ingest Enterprise Search connector content into a graph.
`memory_generate`	Generate a graph from company-search list rows and columns.
`memory_chat`	Chat over graph knowledge with related nodes and edges.

Enterprise Search

Maps to Enterprise Search APIs (agent core URL).

Tool	Purpose
`enterprise_send_chat_message`	Send a message in a chat session (stream or full JSON response).
`enterprise_get_chat_sessions`	List chat sessions for the current user.
`enterprise_create_chat_session`	Create a new chat session.
`enterprise_rename_chat_session`	Rename an existing session.
`enterprise_get_connector_status`	List connector–credential pair status.
`enterprise_get_connectors`	List connectors (optional credential filter).
`enterprise_create_connector`	Create a connector (e.g. web).
`enterprise_get_cc_pair`	Full info for a connector–credential pair.
`enterprise_update_cc_pair_status`	Pause, schedule, or update pair status.
`enterprise_connector_run_once`	Trigger a one-time reindex.
`enterprise_create_deletion_attempt`	Delete a connector and credential.
`enterprise_associate_credential`	Associate a credential with a connector.
`enterprise_upload_project_file`	Upload one project file.
`enterprise_upload_project_files`	Upload multiple project files.
`enterprise_get_project_file_statuses`	Poll upload/indexing status by file IDs.

ℹ️ Note: All string arguments require min_length=1. All integer caps (total_target, max_concurrent_research_units, max_researcher_iterations) require ≥ 1. Empty values or missing required fields surface as validation errors in the error field of the response.

Local Installation

You can also run the Chordian MCP server locally — useful for development, on-prem deployments, or when you want to point at a private agent core or memory service.

Prerequisites

Python ≥ 3.13 (install)
A valid Chordian API key
Network access to your AGENT_CORE_URL and MEMORY_URL (upstream Chordian services)

Verify Python is installed:

python --version

Install and run

git clone https://github.com/chordian-ai/Chordian_MCP_Server.git
cd Chordian_MCP_Server
 
pip install .
python -m app.main

git clone https://github.com/chordian-ai/Chordian_MCP_Server.git
cd Chordian_MCP_Server
 
docker build -t chordian-mcp-server .
docker run -p 8000:8000 \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e AGENT_CORE_URL=https://chordian-core.chordian.ai \
  -e MEMORY_URL=https://graph-kb.chordian.ai \
  chordian-mcp-server

git clone https://github.com/chordian-ai/Chordian_MCP_Server.git
cd Chordian_MCP_Server
 
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .
python -m app.main

By default the MCP SDK listens on 127.0.0.1:8000 with Streamable HTTP unless you override host / port on the FastMCP constructor in app/server.py. Use MCP_HOST=0.0.0.0 in Docker so published ports work as expected.

If the process binds only to localhost inside a container, set FastMCP(..., host="0.0.0.0", port=8000) or equivalent env-driven settings.

Environment variables

Configuration is loaded via pydantic-settings (and .env when present).

Variable	Required for	Default	Purpose
`AGENT_CORE_URL`	Company / people / research / enterprise search tools	`""`	Base URL for company search, people search, research, and enterprise search APIs.
`MEMORY_URL`	Memory tools	—	Base URL for Memory / knowledge graph APIs (e.g. `https://graph-kb.chordian.ai`).
`NWS_API_BASE`, `USER_AGENT`	Weather tools (optional)	—	National Weather Service API base and `User-Agent` if you enable `weather` in `server.py`.
`MCP_HOST`	Transport	`127.0.0.1`	Bind address. Use `0.0.0.0` in Docker or on a server so the process listens on all interfaces.
`MCP_PORT`	Transport	`8000`	TCP port for Streamable HTTP.
`LOG_LEVEL`	Logging	—	Log level (see `app/utils/logger.py`).
`LOG_DIR`	Logging	—	Directory for rotated log files.

Project layout

Path	Role
`app/main.py`	Entrypoint; starts Streamable HTTP transport.
`app/server.py`	`FastMCP` instance, `/health`, and tool module imports.
`app/tools/`	MCP `@mcp.tool()` definitions (per-domain modules).
`app/services/`	HTTP clients and routing to agent core / memory.
`app/schemas/`	Pydantic request models for tool payloads.
`app/auth/`	API key extraction from MCP request context (`middleware.py`).
`app/config/`	Settings.
`app/utils/`	Logging, HTTP helpers.
`app/resources/`	Placeholder for MCP resources (optional).
`tests/`	Smoke tests (`unittest`).

Tests

python -m unittest discover -s tests -p "test_*.py"

Configuring MCP Clients for a local server

Point your client at the local URL with the same x-api-key header pattern.

{
  "mcpServers": {
    "Chordian-MCP-Server-Local": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--header",
        "x-api-key: <api-key>"
      ]
    }
  }
}

Usage Examples

Once Chordian MCP is connected, you can prompt your MCP client in natural language and it will pick the right tool automatically.

Company search

Find B2B SaaS companies in Austin with 50-200 employees, then grow the list to 100 targets.

Calls start_workflow → polls with get_status_workflows → calls continue_workflow with total_target: 100.

Show me all the company-search lists in my Chordian workspace.

Calls get_lists with the API key from your x-api-key header.

People search

Find product managers in Bangalore with fintech experience.

Calls start_people_search, then get_status_people_search until results are ready.

Deep research

Research the competitive landscape for vector databases in 2025. Cap parallel units to 4 and iterations to 6.

Calls start_research with max_concurrent_research_units: 4, max_researcher_iterations: 6, then get_result_of_search once complete.

Enrichment

On the list with id list_xyz789 from thread thread_abc123, enrich the ceo_email column with verified work emails.

Calls start_enrichment with column_name: "ceo_email", enrichment_type: "contacts", and the supplied instruction.

Combined workflow

Find Series B fintech startups in New York, enrich the CEO email column,
then run deep research on the top 5 companies and summarize the findings.

Chains start_workflow → get_status_workflows → start_enrichment → start_research → get_result_of_search.

Memory

List my knowledge graph departments, then chat over graph abc123 about our Q1 pipeline themes.

Calls memory_list_departments → memory_chat with the selected graph_id.

Enterprise search

Show connector status, then send a chat message in my session asking what was indexed from Notion last week.

Calls enterprise_get_connector_status → enterprise_send_chat_message.

Memory APIs — REST endpoints used by memory_* tools
Enterprise Search APIs — REST endpoints used by enterprise_* tools
Company Search APIs — workflows behind start_workflow, get_lists, enrichment, and company_database_search
People Search APIs — workflows behind start_people_search and people_database_search
Deep Research APIs — workflows behind start_research

Health Check

A standard, unauthenticated liveness route for load balancers and orchestrators.

GET /health

{
  "status": "ok",
  "service": "chordian-mcp-server"
}

curl https://mcp.chordian.ai/health

Troubleshooting

Server not found

If your MCP client cannot reach Chordian, verify your environment:

npm --version
node --version

Make sure mcp-remote is reachable through npx (no global install required). Also verify your mcp.json / claude_desktop_config.json is valid JSON — a trailing comma will silently drop the server.

`npx` issues

If you see “command not found”, locate your npx:

# macOS / Linux
which npx
 
# Windows
where.exe npx

ℹ️ Tip: Once you have the path, update your client config to use the full path to npx instead of relying on PATH.

API key issues

When troubleshooting API key problems, verify that your key is:

Sent on the x-api-key header (not Authorization, not query string).
Active in your Chordian workspace.
Spelled correctly in mcp.json — quotation marks, no extra spaces, and the literal value (no Bearer prefix).

You can test connectivity quickly:

curl -i https://mcp.chordian.ai/health

If /health returns 200, the server is reachable; any tool error after that is an auth or upstream issue, not a network problem.

Tool returns `success: false`

Error	Likely cause
`Missing x-api-key header`	Client didn’t forward the header — check your `--header "x-api-key: ..."` arg.
`Unable to start workflow` / `Unable to start people search` / `Unable to start research`	Upstream Chordian agent core returned a non-2xx. Re-check your API key permissions and the prompt content.
Memory / enterprise tool errors	Check `MEMORY_URL` and `AGENT_CORE_URL` are set when running locally; hosted MCP uses Chordian defaults.
Pydantic validation message (e.g. `String should have at least 1 character`)	A required string argument was empty or an integer cap was `< 1`.
`Internal server error`	Unhandled exception on the server — please contact Chordian support with the request ID and timestamp.

Acknowledgments

Model Context Protocol — for the MCP specification.
Anthropic — for Claude Desktop and Claude Code.
Cursor — for first-class MCP support in the IDE.
mcp-remote — for the stdio↔HTTP bridge.

Memory APIs Postman Collections

Chordian MCP Server

Remote MCP Server

Connect to Cursor

Connect to Claude Desktop

Connect to Claude Code

OpenAI

Clients that don’t support remote MCPs

Authentication

Response envelope

Available Tools

Company Search

People Search

Research

Memory

Enterprise Search

Local Installation

Prerequisites

Install and run

Environment variables

Project layout

Tests

Configuring MCP Clients for a local server

Usage Examples

Company search

People search

Deep research

Enrichment

Combined workflow

Memory

Enterprise search

Related API reference

Health Check

Troubleshooting

Server not found

npx issues

API key issues

Tool returns success: false

Acknowledgments

`npx` issues

Tool returns `success: false`