MCP API (Model Context Protocol)

The MCP endpoint exposes The Org API as Model Context Protocol  (MCP) tools. Use it from MCP-compatible clients (Cursor, Claude, ChatGPT, and others) 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

The MCP server supports OAuth in full, and it also accepts an API key. Credit costs match the underlying operations (list tools are free). An OAuth connection is issued its own API key, so credits, rate limits, and the 30-minute org-chart exploration pass are tracked on that connection separately from a key you paste yourself.

OAuth

Clients that implement MCP authorization  connect with the server URL alone. A request without credentials returns 401 and a WWW-Authenticate header pointing at the protected-resource metadata, which is how the client starts the flow.

The grant is authorization code with PKCE. code_challenge_method must be S256. Clients are public (token_endpoint_auth_method is none). Supported scopes are openid, email, and mcp. Client ID metadata documents are accepted. After you approve the connection on The Org, the token response is a Bearer access token with expires_in of 365 days. Send it on MCP calls as Authorization: Bearer.

Userinfo returns sub, email, and email_verified.

API key

Pass the same API key as the rest of the API in the X-Api-Key header, or as the api_key query parameter (apikey and x-api-key are also accepted). The examples below use the header.

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.

HEAD, and GET without Accept: text/event-stream, return 200 so clients can probe the URL. SSE streaming is not supported. Send JSON-RPC messages with POST.

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).

Free-tool windows are per API key and shared with the matching REST route. Details: Rate Limiting.

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 walk the chart as JSON, use the exploration tools below. The HTTP Company API org chart endpoint is a separate charge (10 credits per request).

Org-chart exploration

get_company_executive_positions, get_company_position_reports, and search_company_positions read one company’s chart. If the question is about that company’s org chart structure, these tools need companyId, a UUID. Identify the company and that id with search_companies (or get_company) first. A name or slug is rejected.

The first call that finds the company, on a given API key and company, costs 10 credits and opens a 30-minute exploration pass. An OAuth connection counts as its own API key. An unknown company id is not charged. Further calls for that pair inside the window are free, including paging get_company_position_reports and search_company_positions. A different company, or the same company on another key or connection, starts a new pass. If fewer than 10 credits remain, the tool result is an error and no pass is stored. This window is separate from the 24-hour replay on metered REST requests.

These tools do not replace get_manager / get_reports, which look a person up by position id, email, or LinkedIn and cost 1 credit per find.

get_company_executive_positions

Company profile fields plus the top of the chart: l1 (roots), l2 (their direct reports), advisers, and section counts (placed, unplaced, board, total). Each entry can be a person, a job, or a group.

Each entry includes nodeId, title, name, linkedInUrl, theOrgUrl, nodeType (position for a person, job, or coManager for a group), section (orgChart, unplaced, or board), parentNodeId, reportCount, and seniorityScore. name is null for jobs and groups.

get_company_position_reports

Direct reports of one person, job, or group. This is not get_reports, which looks a person up by position id, email, or LinkedIn.

The response contains node, reports, totalReports, limit, offset, and hasMore.

search_company_positions

Search that company’s chart by name or title. Matches people, jobs, and groups.

The response contains companyId, results, and totalCount.

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.