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 companies, people, open jobs, org charts, reporting lines, positions, contact details, people/lead lists, 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

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 (list tools are 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.

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

GET (SSE streaming) is not supported; use POST for all JSON-RPC messages.

Tools

List tools return a url for each list in the form https://theorg.com/people/lists/{slug} (for example https://theorg.com/people/lists/empty-list). The same lists can be read over HTTP via the Lists API (GET /v1.1/lists).

Every tool declares a JSON Schema outputSchema in tools/list, and successful tools/call results carry the typed payload in structuredContent alongside the human-readable content text block.

Recommended routing

Filter fields for find_positions match the Position API. Company/org-chart tools match the Company API. MCP find_positions and find_jobs limit results to 25 per call (stricter than the Position API’s page size of up to 1000).

Company tools

search_companies

Look up companies and return ids, names, domains, org-chart URLs, and signed embed URLs. Provide any one of the following:

get_company

Returns an enriched company profile. Provide exactly one identifier.

The response company object includes id, name, slug, description, logoUrl, domains, websiteUrl, linkedInUrl, twitterUrl, industry, industries, legalStatus, stage, foundedYear, employeeRange, location, totalFundingUsd, latestFundingStage, crunchbaseUrl, positionCount, followerCount, verified, orgChartUrl, and embedUrl.

industries, legalStatus, employeeRange, and latestFundingStage use the same vocabulary as the find_positions filters, so a company profile can be fed straight back into a people search.

get_org_chart

Returns an iframe embed URL for a company’s org chart rather than the chart data itself, which keeps large charts out of the model’s context.

The response contains name, embedUrl, and orgChartUrl. Render embedUrl in an iframe; it is signed to your API key. To retrieve the chart nodes as JSON instead, call the Company API org chart endpoint over HTTP (10 credits per request).

Person and job lookup tools

find_person

Look up a specific person in The Org’s people index. Prefer this over find_positions when you already have a LinkedIn profile or a name+company pair.

Provide either linkedInUrl, or fullName with companyName or companyDomain:

The response contains people entries with positionId, fullName, title, slug, linkedInUrl, companyId, companyName, companySlug, profileUrl, and orgChartUrl. Use returned positionId values with get_manager, get_reports, resolve_contacts, and list tools.

find_jobs

Search open job vacancies. Resolve a specific posting via jobUrl or companySlug + jobSlug, or search with title/keywords and optional company/filters.

The response contains jobs and totalResults. Each job includes jobId, title, slug, teaser, remote, jobType, jobFunction, country, company fields, jobUrl, and optional associatedPositionId when the role is placed on the org chart.

Reporting-line tools

get_manager walks one step up the reporting line and get_reports walks one step down. Both accept the same identifiers — provide any one of them.

get_manager returns data.position and data.manager (null when the person is at the top of the chart). get_reports returns data.position, data.reports, and data.totalReports. At most 50 reports are returned per call; totalReports always carries the true count.

Both cost 1 credit per successful lookup — get_manager when a manager is found, get_reports when at least one report is found.

find_positions arguments

find_positions filters

filters accepts the same fields as the Position API, including:

resolve_contacts

Actively resolves work emails for people you have already found via find_positions or find_person.

The workEmail field on a find_positions row only reflects whether an email is already stored — it is not a resolution attempt. A null there does not mean no email can be found. Call resolve_contacts before concluding that contact details are unavailable.

The response contains data.creditsUsed and data.results, with one entry per requested person holding positionId, emails (each with email, emailType, and verification), and phoneNumbers. A person with no resolvable email comes back with empty arrays rather than being omitted.

Credits: 1 credit per person newly resolved to an email. People this account has resolved before are free, and people for whom no email is found cost nothing. If the batch is larger than your remaining balance, only as many people as you can afford are attempted, so a call never overdraws. Phone numbers are read from existing data and are never charged for.

People / lead list tools

Use find_positions or find_person first, then pass returned position IDs into create_list or add_to_list.

get_lists

Response includes lists (each with id, name, slug, url, optional positionCount) and total.

add_to_list

create_list

Response includes the created/updated list (id, name, slug, url) and addedCount.

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" }
    }
  }'

Example: Call get_company

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": 5,
    "method": "tools/call",
    "params": {
      "name": "get_company",
      "arguments": { "domain": "theorg.com" }
    }
  }'

Example: Call find_person

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": 12,
    "method": "tools/call",
    "params": {
      "name": "find_person",
      "arguments": {
        "fullName": "Patrick Collison",
        "companyName": "Stripe"
      }
    }
  }'

Example: Call find_jobs

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": 13,
    "method": "tools/call",
    "params": {
      "name": "find_jobs",
      "arguments": {
        "jobTitle": "Product Manager",
        "companyName": "Stripe",
        "limit": 5
      }
    }
  }'

Example: Call find_positions

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": 6,
    "method": "tools/call",
    "params": {
      "name": "find_positions",
      "arguments": {
        "limit": 5,
        "offset": 0,
        "filters": {
          "companyDomains": ["theorg.com"],
          "jobTitles": ["CTO", "Chief Technology Officer"]
        }
      }
    }
  }'

Example: Call get_reports

Use a position id returned by find_positions:

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": 7,
    "method": "tools/call",
    "params": {
      "name": "get_reports",
      "arguments": { "positionId": 12345 }
    }
  }'

Example: Call resolve_contacts

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": 8,
    "method": "tools/call",
    "params": {
      "name": "resolve_contacts",
      "arguments": { "positionIds": [12345, 12346] }
    }
  }'

Example: Call get_lists

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": 9,
    "method": "tools/call",
    "params": {
      "name": "get_lists",
      "arguments": { "limit": 30, "offset": 0 }
    }
  }'

Example: Call create_list

After find_positions, pass returned position IDs:

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": 10,
    "method": "tools/call",
    "params": {
      "name": "create_list",
      "arguments": {
        "name": "Fintech CTOs",
        "positionIds": [12345, 12346]
      }
    }
  }'

Example: Call add_to_list

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": 11,
    "method": "tools/call",
    "params": {
      "name": "add_to_list",
      "arguments": {
        "slug": "empty-list",
        "positionIds": [12345, 12346]
      }
    }
  }'

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