MCP server

Connect Claude Code in one command:

claude mcp add --transport http xverum https://mcp.xverum.com/mcp

Any other MCP client: point it at https://mcp.xverum.com/mcp. Building against the raw REST API instead? See its OpenAPI spec.

The Xverum MCP server exposes Ask Xverum to AI agents (Claude Desktop, Claude Code, or any Model Context Protocol client) as tools — search people and companies, fetch a full profile or company record, and score job-change likelihood, without calling the REST API directly. It is a hosted, multi-tenant gateway operated by Xverum — nothing to install or run; sign in with OAuth.

Try the demo server — no signup required

To try the tools before you register, point your client at the demo endpoint instead. It serves the same tool names on a fixed synthetic sample catalogue — no account, no credits, no billing:

{
  "mcpServers": {
    "xverum-demo": {
      "url": "https://mcp.xverum.com/demo"
    }
  }
}

Call search_people_xverum (the query is ignored — it returns the fixed demo set), then pass a returned id such as 9990000001 ("Maya Demo", an AI Engineer) to enrich_person_xverum and predict_job_change_xverum. Every demo result is fictional — no id is a real person. For real data, sign in and use the main server below.

Setup

1. Sign in with OAuth

On first connect your MCP client opens a browser to sign in at myaccount.xverum.com; once you approve, the client holds an OAuth session tied to your Xverum account. You need an active account — create one at myaccount.xverum.com if you do not have one yet.

2. Register with Claude Desktop

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "xverum": {
      "url": "https://mcp.xverum.com/mcp"
    }
  }
}

The first time the client connects it opens a browser for the OAuth sign-in; after you approve, the client stores the session.

3. Register with Claude Code

claude mcp add --transport http xverum https://mcp.xverum.com/mcp

On the first call Claude Code runs the OAuth flow in your browser; run /mcp to trigger or re-authenticate it.

4. Register with Cursor

Open Cursor Settings → Tools & MCPs → Add Custom MCP, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "xverum": {
      "url": "https://mcp.xverum.com/mcp"
    }
  }
}

Restart Cursor. The first time it connects, it opens the OAuth sign-in in your browser.

5. Register with VS Code (Copilot)

Create or edit .vscode/mcp.json in your workspace root. VS Code uses a servers key and needs the transport type:

{
  "servers": {
    "xverum": {
      "type": "http",
      "url": "https://mcp.xverum.com/mcp"
    }
  }
}

Reload the window. Copilot picks up the server and prompts for the OAuth sign-in on first use.

6. Register with Codex (OpenAI)

codex mcp add xverum --url https://mcp.xverum.com/mcp

Then authenticate:

codex mcp login xverum

This opens the OAuth sign-in in your browser. After you approve, verify with codex mcp list.

7. Register with ChatGPT

ChatGPT supports remote MCP connectors:

1. Open ChatGPT (chatgpt.com or the desktop app).
2. Open the Apps panel.
3. Click Add custom app → MCP.
4. Enter the server URL: https://mcp.xverum.com/mcp.
5. Complete the OAuth sign-in when prompted.

8. Register with Gemini CLI

Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "xverum": {
      "httpUrl": "https://mcp.xverum.com/mcp"
    }
  }
}

Gemini CLI uses httpUrl, not url.

9. Register with the Gemini app

In the Gemini app, open Settings → Extensions → Add MCP server and enter:

• Server URL: https://mcp.xverum.com/mcp
• Transport: HTTP

Complete the OAuth sign-in when prompted.

10. Register with Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "xverum": {
      "serverUrl": "https://mcp.xverum.com/mcp"
    }
  }
}

Windsurf uses serverUrl, not url. Restart Windsurf; it prompts for the OAuth sign-in on first connection.

11. Verify

Restart your client, or run /mcp in Claude Code. Complete the OAuth sign-in if prompted. You should see xverum listed with the tools search_people_xverum, enrich_person_xverum, predict_job_change_xverum, search_company_xverum and enrich_company_xverum.

Tools

All five tools are read-only. The samples below are synced from the public tools reference, so this page and that repo cannot disagree. Each request is written as the call an agent makes; each response is the payload it gets back, which arrives on the wire inside result.structuredContent.

search_people_xverum

Search professional profiles with a natural-language query. Maps to POST /v1/search.

Coverage: 750M profiles across 220 countries and territories.

Returns results (an array of profile cards with id, social_url, full_name, headline, location, company_name, position, industry, evidence_summary), plus result_type, total_count, page, page_size, credits_used, credits_remaining, and request_id — the same shape as the REST endpoint.

Any of the profile-card fields can be null — Search documents what each null means (for example, industry is null when the person's current employer or its industry is not known).

evidence_summary is a freshness label on each profile — from Verified last 30 days down to Verified over 120 days ago — so an agent can weigh how current a match is before acting on it.

Each result costs 1 credit, so ask for the smallest page_size that answers the question.

Example request:

search_people_xverum("senior ML engineer in Berlin with PyTorch experience", page_size=1)

Example response:

{
  "result_type": "people",
  "results": [
    {
      "id": "482910371",
      "social_url": "https://linkedin.com/in/john-doe2",
      "full_name": "John Doe",
      "headline": "Senior ML Engineer at DeepMind",
      "location": "Berlin, Germany",
      "company_name": "DeepMind",
      "position": "Senior ML Engineer",
      "industry": "artificial intelligence",
      "evidence_summary": "Verified last 30 days"
    }
  ],
  "total_count": 38,
  "page": 1,
  "page_size": 1,
  "credits_used": 1,
  "credits_remaining": 4999,
  "request_id": "9f1c2a7e6b3d4f08"
}

enrich_person_xverum

Fetch one person's full profile by id — employment history, education and background. Maps to GET /v1/profiles/{id}.

Coverage: 750M profiles across 220 countries and territories.

Example request:

enrich_person_xverum("482910371")

Example response:

{
  "social_url": "https://linkedin.com/in/john-doe2",
  "full_name": "John Doe",
  "headline": "Senior ML Engineer",
  "location": "Berlin, Germany",
  "company_name": "DeepMind",
  "position": "Senior ML Engineer",
  "industry": "artificial intelligence",
  "evidence_summary": "Verified last 30 days",
  "experience": [
    {
      "position": "Senior ML Engineer",
      "company_name": "DeepMind",
      "start_time": "Mar 2022",
      "end_time": null,
      "duration": "3 yrs 2 mos",
      "location": "Berlin, Germany",
      "job_description": "Developing and deploying large-scale recommendation models.",
      "industry": "artificial intelligence"
    }
  ],
  "education": [
    {
      "social_url": "https://linkedin.com/school/tu-berlin",
      "institution_name": "TU Berlin",
      "degree": ["MSc Computer Science"],
      "start_time": "2015",
      "end_time": "2017",
      "description": null
    }
  ],
  "about_me": "Building production ML systems at scale.",
  "credits_used": 4,
  "credits_remaining": 4995,
  "request_id": "1a2b3c4d5e6f7081"
}

The payload adds evidence_summary — the same freshness label the search results carry — alongside the profile fields.

One call returns the whole profile and costs 4 credits. A repeat fetch of the same id within a short window re-reads fresh data but charges 0. The payload matches the REST endpoint exactly — see Get profile for the full field list, including what each nullable field means. In an experience entry, an ongoing role reads end_time: "Present"; end_time: null simply means no end date was on record in the source profile.

predict_job_change_xverum

Score how likely a person is to change role before they declare they're open to work — a weekly-rescored probability for outreach timing in recruiting, deal-risk alerts on champions in sales, and talent-movement analysis. Powered by Next Move Signal. Maps to GET /v1/profiles/{id}/job-change.

Coverage: The same 750M profiles across 220 countries and territories. A score is available only when we have enough signals of an impending role change; we calculate it as soon as those signals are observed.

Returns has_prediction, and — when it is true — a score between 0 and 1, a signal_date, and a reasoning array of the factors behind the score, plus credits_used, credits_remaining and request_id.

Read `has_prediction` first. The signal is precision-first — it fires only above a confidence floor, so a profile either carries a high-confidence score or returns has_prediction: false with credits_used: 0, never a low-confidence guess. false is an answer, not a failure — retrying it will not change the outcome. A profile_not_found error means no such profile, which is a different thing.

Each score costs 10 credits, and `0` when no prediction is held.

Example request:

predict_job_change_xverum("482910371")

Example response when a prediction is held:

{
  "has_prediction": true,
  "score": 0.87,
  "signal_date": "2026-05-09",
  "reasoning": [
    { "category": "tenure_in_role", "intensity": "high", "weight": 0.31, "rank": 1 },
    { "category": "company_signal", "intensity": "medium", "weight": 0.12, "rank": 2 }
  ],
  "credits_used": 10,
  "credits_remaining": 4986,
  "request_id": "1a2b3c4d5e6f7081"
}

Example response when no prediction is held — nothing charged:

{
  "has_prediction": false,
  "score": null,
  "signal_date": null,
  "reasoning": [],
  "credits_used": 0,
  "credits_remaining": 4996,
  "request_id": "1a2b3c4d5e6f7081"
}

signal_date is when the evidence was observed, not when the score was refreshed, so an older date does not make a score stale.

search_company_xverum

Search companies with a natural-language query. Maps to POST /v1/search with target: "company".

Coverage: 54M company profiles.

Returns results (an array of company cards with id, social_url, company_name, slogan, headquarters, country_code, industry, employees_num, website, founded, evidence_summary), plus result_type, total_count, page, page_size, credits_used, credits_remaining, and request_id — the same envelope as search_people_xverum, with company cards in place of profiles.

Any company-card field except id can be null — Search for companies documents what each null means.

evidence_summary is a freshness label on each company — from Verified last 30 days down to Verified over 120 days ago — the same label the people tools carry, so an agent can weigh how current a record is.

Each result costs 1 credit, the same rate as people search, so ask for the smallest page_size that answers the question. Pass a returned id to enrich_company_xverum for the company's full record.

Example request:

search_company_xverum("cybersecurity companies in Germany", page_size=1)

Example response:

{
  "result_type": "company",
  "results": [
    {
      "id": "88673718",
      "social_url": "https://linkedin.com/company/cloumo",
      "company_name": "Cloumo GmbH",
      "slogan": null,
      "headquarters": "Munich, Bavaria",
      "country_code": "de",
      "industry": "IT Services and IT Consulting",
      "employees_num": 14,
      "website": "https://www.cloumo.com",
      "founded": 2021,
      "evidence_summary": "Verified last 90 days"
    }
  ],
  "total_count": 1259,
  "page": 1,
  "page_size": 1,
  "credits_used": 1,
  "credits_remaining": 1521,
  "request_id": "6d966bdee75646c8"
}

enrich_company_xverum

Fetch one company's full record by id — description, specialties, office locations, organisation type, follower count and funding. Maps to GET /v1/companies/{company_id}.

Coverage: The same 54M company profiles that search covers.

Returns the company-card fields (social_url, company_name, slogan, headquarters, country_code, industry, employees_num, website, founded, evidence_summary) plus the detail fields about_us, specialties, locations, type, social_followers and funding, alongside credits_used, credits_remaining and request_id. Any field can be null (or an empty list) when it is not on record for the company. evidence_summary is the same freshness label the search results carry.

One call returns the whole record and costs 4 credits. A repeat fetch of the same id within a short window re-reads fresh data but charges 0.

Example request:

enrich_company_xverum("88673718")

Example response:

{
  "social_url": "https://linkedin.com/company/cloumo",
  "company_name": "Cloumo GmbH",
  "slogan": null,
  "headquarters": "Munich, Bavaria",
  "country_code": "de",
  "industry": "IT Services and IT Consulting",
  "employees_num": 14,
  "website": "https://www.cloumo.com",
  "founded": 2021,
  "evidence_summary": "Verified last 90 days",
  "about_us": "Cloumo GmbH is an IT services company based in Munich...",
  "specialties": ["IT", "Cloud", "M365", "IT-Sicherheit", "and IT-Helpdesk"],
  "locations": [
    {
      "address": "Leopoldstraße 87",
      "address_2": "Munich, Bavaria 80802, DE",
      "primary": true
    }
  ],
  "type": "Self-Owned",
  "social_followers": 47,
  "credits_used": 4,
  "credits_remaining": 1517,
  "request_id": "7e2f3a8b9c1d4e05"
}

Rate limits and billing

Tool calls count against the same per-key quota as direct API calls — 60 requests/minute by default. Credits are charged identically: 1 credit per search result (people or companies), 4 credits per profile or company fetch, and 10 credits per job-change score (0 when no prediction is held). Every response echoes credits_used and credits_remaining. See Rate limits.

Errors

All five tools surface the structured /v1 error envelope (see Authentication) as an agent-readable tool error. Some conditions are worth retrying, others are not:

The off_topic_query message is advisory and target-specific — branch on error.code, not its text. On search_company_xverum an off-topic query returns "Query is not a company search. If you were looking for people, retry with target=people." instead, pointing a mis-targeted search at search_people_xverum.

Troubleshooting