Quickstart¶

This page walks you from "nothing installed" to "Claude Desktop is calling Compass tools through MCP" in about five minutes.

1. Get an API key¶

Application keys are minted by a Chordia admin via the REST API:

curl -X POST https://compass.chordia.ai/projects/$PROJECT_ID/mcp-keys \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "My laptop — Claude Desktop"}'

The response — exactly once — returns the bearer token under key. Save it; subsequent reads only show key_preview.

For supervisor- or agent-scoped keys, see Authentication & RBAC → minting scoped keys.

2. Boot the MCP server locally (optional)¶

If you're integrating against a hosted instance, skip to step 3. If you want to run the server yourself:

# from the repo root
MCP_SERVER_ENABLED=1 bash start.sh
# or, on its own:
cd src && python -m mcp_server

Default port is 8001. Sanity-check it's up:

curl http://localhost:8001/health
# → {"status":"ok","server":"chordia-compass-mcp","tools":12,"auth_cache_size":0}

3. Wire a client¶

Claude Desktop¶

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) — same path with different roots on Linux/Windows:

{
  "mcpServers": {
    "chordia-compass": {
      "transport": "sse",
      "url": "https://mcp.chordia.ai/sse",
      "headers": {
        "Authorization": "Bearer YOUR_APPLICATION_KEY"
      }
    }
  }
}

Restart Claude Desktop. Tools and resources appear under the 🔌 menu.

Cursor¶

Cursor → Settings → MCP → Add server, paste the same JSON.

Python (one-shot smoke test)¶

import asyncio
from fastmcp import Client
from fastmcp.client.auth import BearerAuth

async def main():
    async with Client(
        "https://mcp.chordia.ai/mcp",
        auth=BearerAuth("YOUR_APPLICATION_KEY"),
    ) as client:
        tools = await client.list_tools()
        print(f"Server has {len(tools)} tools: {[t.name for t in tools]}")

        result = await client.call_tool("get_project_context", {})
        print(result.content[0].text[:500])

asyncio.run(main())

4. What to call first¶

The conventional pattern is:

get_project_context — orientation: agent roster, volume, signal catalog with frequencies. Always called once at the start of a chat so the LLM understands which client it's looking at.
search_calls — list candidate calls matching some filter.
get_call_detail with a session_id from step 2 — drill into one call's full evaluation + transcript.
query_interactions — escape hatch when the above don't compose into the analytic the user is asking for. Takes a guarded MongoDB aggregation pipeline.

See the Tools reference for the full inventory.

Troubleshooting¶

Authentication required — your Authorization: Bearer … header is missing or malformed. Verify with curl -v and check the server log for MCP auth via application_key: project_id=… after a successful match.

Knowledge base not configured for this project — the project hasn't enabled a KB. See admin/knowledge-base setup.

Tools list is empty — the registry didn't populate. Hit /ready; if it returns 503, the import chain failed. Check the server logs.