MCP API (Model Context Protocol)

The MCP endpoint exposes The Org API as Model Context Protocol (MCP) tools. Use it from MCP-compatible clients (e.g. Cursor, Claude Desktop) to query org charts, managers, position search, and usage over JSON-RPC 2.0.

For setup instructions (Claude Desktop, Cursor), see MCP Integration.

Endpoint


POST https://api.theorg.com/v1.1/mcp

Parameter	Value
Url	https://api.theorg.com/v1.1/mcp
Method	`POST`
Auth	`X-Api-Key` (same as other API)
Cost	Same credits as underlying APIs

Authentication uses the same API key as the rest of the API. Pass it in the X-Api-Key header. Credit costs match the underlying operations (e.g. org chart 10 credits, manager 1 credit, positions 1 per row, usage free).

Optional: send MCP-Protocol-Version: 2025-11-25 (or 2025-03-26) on requests.

Protocol

The transport is Streamable HTTP : each JSON-RPC message is a separate POST with a JSON body.

Initialize – Send an initialize request; the server returns capabilities and server info.
Initialized – Send a notifications/initialized notification (server responds 202 Accepted).
Tools – Use tools/list to discover tools and tools/call to invoke them.

Tools

Tool	Description	Credits
`get_org_chart`	Full org chart by domain or LinkedIn	10 per request
`get_manager`	Manager of a person (email/LinkedIn)	1 per find
`get_usage`	Current account usage/credits	Free
`find_positions`	Search positions with filters	1 per row

Inputs match the Company API and Position API (e.g. domain, linkedInUrl, section for org chart; limit, offset, filters for positions).

Example: Initialize


curl --location 'https://api.theorg.com/v1.1/mcp' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "example", "version": "1.0" }
    }
  }'

Example: List tools


curl --location 'https://api.theorg.com/v1.1/mcp' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Example: Call a tool (get_usage)


curl --location 'https://api.theorg.com/v1.1/mcp' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": { "name": "get_usage", "arguments": {} }
  }'

Example: Call get_org_chart


curl --location 'https://api.theorg.com/v1.1/mcp' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_org_chart",
      "arguments": { "domain": "theorg.com" }
    }
  }'

Error responses use standard JSON-RPC 2.0 errors or tool results with isError: true and a message in the content.