SignalHire MCP Server - SignalHire API

The SignalHire MCP server lets AI assistants and agents query our dataset of professional profiles, company information, and contact details — directly from Claude, Cursor, Windsurf, VS Code, or any MCP-compatible client.

Getting Started

Step 1 — generate your API key

Nothing works until your SignalHire account has an API key. Generate it once:

Open your profile

Go to signalhire.com/profile.

Open the Integrations section

Direct link: signalhire.com/apiIntegrations.

Generate the key

Generate an API key and copy it.

This step is required even if you connect through OAuth. The OAuth paths never ask you to type a key, but the token they issue carries your account’s key inside it — an account without one produces a token the server rejects with 401. Generate the key first, then connect however you like.

You also need:

An active SignalHire account (see the account rules under Authentication)
Contact credits, if you plan to reveal emails and phone numbers

Starter prompts

Once connected, paste one of these to get a real result on the first try. None of them spends a Contact Credit:

Find 5 software engineers in New York and show me their profiles.

Which seniority levels and departments can I filter by?

How much of my daily search quota is left?

From there, ask the assistant to reveal contacts for a specific candidate — it will ask your permission before spending anything.

Connection Details


Endpoint	`https://mcp.signalhire.services/mcp`
Transport	MCP Streamable HTTP

Authentication

The server is a stateless proxy — it stores no global key and forwards your credential per request. It detects the token type automatically.

Mode	How	When to use
API key (Bearer)	HTTP header `Authorization: Bearer <YOUR_API_KEY>` in a JSON config	IDEs and services configured via JSON, programmatic clients, automation
OAuth 2.0 (Auth0)	Interactive login, no key typed by hand	Claude.ai / Claude Desktop connector UI, the ChatGPT app directory

Both modes need an API key on the account. With OAuth you never type it — the Auth0 token carries it as a claim and the server reads it from there. But the key has to exist: if the account has none, the claim is empty and every request comes back 401. Generate it first.

You must sign in with an existing SignalHire account. Whichever way you authenticate, the connector attaches to an account that already exists — the OAuth screen is a login, not a sign-up, and there is no way to create an account from inside the AI client. Register at signalhire.com first if you don’t have one.The account you sign in with is the account that gets charged, and its credits and daily quota are the ones the tools report. If you keep several SignalHire accounts, make sure the right one is the active session in your browser before you start the OAuth flow — the connector binds to whoever is logged in, and switching afterwards means disconnecting and reconnecting. On the API-key paths the same rule applies through the key itself: a key belongs to one account, so grabbing it from the wrong login silently bills the wrong balance.Signing in with a social login? Check which one. If your SignalHire account was created through a social provider rather than an email and password, you have to sign in through that same provider and with the same identity behind it. Browsers routinely keep several accounts of one provider signed in at once and will hand the flow whichever is default, without asking. Read the account shown on the provider’s screen before you confirm, and use its account picker — or a private window — if more than one is in play. Picking the wrong one does not produce an error: it authorises a different SignalHire identity, and you land on an account with someone else’s credits, or on an empty one.

OAuth details. OAuth is handled by SignalHire’s Auth0 authorization server (https://signalhire.eu.auth0.com/). When you add the connector, the client (Claude or ChatGPT) discovers the authorization server via RFC 9728 metadata, you log in and consent on the SignalHire/Auth0 screen, and the client receives a token — no API key is entered by hand. Expired tokens return 401 and the client refreshes them automatically.

Connecting via JSON (API key)

There are two JSON connection types depending on whether your client can talk to a remote server directly.

Type 1 — Direct HTTP (Claude Code, Cursor, Windsurf, VS Code)

The client speaks MCP Streamable HTTP straight to the server. No Node.js, no bridge. This is the preferred type — use it whenever your client supports it. Get the key from your API integrations page.

{
  "mcpServers": {
    "SignalHire": {
      "type": "http",
      "url": "https://mcp.signalhire.services/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SIGNALHIRE_API_KEY"
      }
    }
  }
}

Per-client differences (everything else stays the same):

Client	Config file	Difference
Claude Code	`.mcp.json` (project root)	None — use as-is
Cursor	`~/.cursor/mcp.json` or `.cursor/mcp.json` (Windows: `%USERPROFILE%\.cursor\mcp.json`)	Omit the `"type"` field
Windsurf	`~/.codeium/windsurf/mcp_config.json`	Rename `"url"` → `"serverUrl"`
VS Code (Copilot agent mode)	`.vscode/mcp.json`	Rename `"mcpServers"` → `"servers"`

VS Code without editing JSON: Command Palette → MCP: Add Server → HTTP → URL https://mcp.signalhire.services/mcp → name it SignalHire → add the header Authorization with the value Bearer YOUR_SIGNALHIRE_API_KEY.

Type 2 — mcp-remote bridge (Claude Desktop and stdio-only clients)

Some clients can only launch a local stdio process and cannot open a remote connection themselves — most notably Claude Desktop. For those, npx mcp-remote runs locally and bridges stdio to the remote HTTP endpoint. Requires Node.js installed.

{
  "mcpServers": {
    "SignalHireMCP": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.signalhire.services/mcp",
        "--header",
        "Authorization: Bearer YOUR_SIGNALHIRE_API_KEY"
      ]
    }
  }
}

Claude Desktop config path:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Which type do I use?

Your client	Type
Claude Code, Cursor, Windsurf, VS Code	Type 1 — Direct HTTP
Claude Desktop (JSON config), or any stdio-only client	Type 2 — mcp-remote bridge
Claude.ai / Claude Desktop connector UI	Neither — use OAuth (no JSON needed)
ChatGPT	Neither — install from the app directory; see the ChatGPT section
Codex	Neither — TOML config; see the Codex section
n8n	Neither — MCP Client Tool node; see the n8n section

Claude.ai / Claude Desktop — Custom Connector (OAuth)

Open Connectors settings

Go to Settings → Connectors → Add custom connector.

Enter the endpoint URL

Set the URL to https://mcp.signalhire.services/mcp

Connect

Leave the advanced OAuth fields empty and click Connect — you’ll be redirected to the SignalHire login (Auth0). After consent no API key is needed.

ChatGPT — app directory

Connect via SignalHire’s official listing in the ChatGPT app directory. No URL, no client ID and no API key.

Open the directory listing

Go to chatgpt.com/apps?q=signalhire.

Connect

Click Connect.

Authenticate

Complete OAuth authentication — you’ll be redirected to the SignalHire login (Auth0) and back.

Verify the tools

Open any chat, click the tools menu, and confirm the SignalHire tools are listed.

Prefer not to use OAuth? Any ChatGPT client that reads a JSON MCP config can use the API-key form shown above (Authorization: Bearer YOUR_SIGNALHIRE_API_KEY).

Codex — TOML config (API key)

Codex speaks Streamable HTTP to remote MCP servers and reads its config from ~/.codex/config.toml (or a project-scoped .codex/config.toml). Get your key from the API integrations page.

[mcp_servers.signalhire]
url = "https://mcp.signalhire.services/mcp"
bearer_token_env_var = "SIGNALHIRE_API_KEY"

Then export the key before starting Codex:

export SIGNALHIRE_API_KEY=YOUR_SIGNALHIRE_API_KEY

bearer_token_env_var makes Codex send Authorization: Bearer <value> — exactly what this server expects, and it keeps the key out of the config file. To register the server from the CLI instead of editing TOML:

codex mcp add signalhire --url https://mcp.signalhire.services/mcp

Use the API-key form above rather than codex mcp login — SignalHire’s authorization server issues OAuth clients for the Claude and ChatGPT directory listings, not for arbitrary clients registering themselves.

n8n — MCP Client Tool node

Requires n8n 1.88.0 or newer. Get your key from the API integrations page.

Add the node

Add an MCP Client Tool node to your workflow.

Set the transport

Set Server Transport / Connection Type to HTTP Streamable.

Enter the endpoint

Set Endpoint / URL to https://mcp.signalhire.services/mcp

Authenticate

Choose Bearer Auth and paste your SignalHire API key as the token. If your n8n version only offers Header Auth, use header name Authorization and value Bearer YOUR_SIGNALHIRE_API_KEY — both produce the same request.

Wire it up

Select which tools to expose, then connect the node to your AI Agent node.

Store the key in n8n’s built-in Credentials system rather than typing it into the node field, so it isn’t written into the exported workflow.

Any other MCP client

Not on the list above? Anything that speaks MCP over Streamable HTTP will work — there is nothing client-specific on our side. Point it at:


URL	`https://mcp.signalhire.services/mcp`
Transport	MCP Streamable HTTP (not SSE — the legacy `/sse` endpoint is retired)
Auth header	`Authorization: Bearer YOUR_SIGNALHIRE_API_KEY`

Get the key from your API integrations page. If your client can only launch local stdio processes, use the mcp-remote bridge from Type 2 above.

Claude Code — CLI

claude mcp add --transport http SignalHire https://mcp.signalhire.services/mcp \
  --header "Authorization: Bearer YOUR_SIGNALHIRE_API_KEY"

Python SDK (programmatic)

MCP client directly
Anthropic SDK (MCP connector)

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

url = "https://mcp.signalhire.services/mcp"
headers = {"Authorization": "Bearer YOUR_SIGNALHIRE_API_KEY"}

async with streamablehttp_client(url, headers=headers) as (read_stream, write_stream, _):
    async with ClientSession(read_stream, write_stream) as session:
        await session.initialize()
        tools = await session.list_tools()
        print(tools)

Claude connects to the server itself, so you don’t run an MCP client. Both the mcp_servers entry and the matching mcp_toolset in tools are required — sending only the first is rejected as a validation error.

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.signalhire.services/mcp",
        "name": "signalhire",
        "authorization_token": "YOUR_SIGNALHIRE_API_KEY",
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "signalhire"}],
    messages=[{"role": "user", "content": "Find senior engineers in San Francisco"}],
)

Available Tools

Once connected, your AI assistant can call the following tools and decides which to use based on your prompt.

Response format: the five data tools — search_candidates_query, scroll_search, retrieve_person_no_contacts, retrieve_person_profile, get_company_info — accept a response_format parameter (default "markdown"); set it to "csv" or "json" as needed. find_company, the two balance tools and the three dictionary tools do not take it.Credits: the remaining balance is automatically appended to the tool’s response — no separate balance check is needed after each call.

Search & Discovery

tool

Search the database using advanced filters like title, location, and keywords. Supports Boolean logic (e.g. (Software AND Engineer)). Parameters: current_title, current_past_title, location, current_company, current_past_company, full_name, keywords, industry, industries, department (Enum), level (Enum), years_experience_from, years_experience_to, years_current_past_experience_from, years_current_past_experience_to, open_to_work, exclude_revealed, exclude_watched, exclude_in_lists, exclude_in_progress, exclude_emailed, size (default: 10), response_format.Credit cost: Uses daily search quota. No contact credits.

tool

Fetch the next batch of search results for pagination. Must be called within 15 seconds of the initial search. Parameters: request_id, scroll_id, response_format.Credit cost: Uses daily search quota.

Profile Retrieval

tool

Retrieve a candidate’s full professional profile (experience, skills, education) without unlocking contact details. Parameters: items (array of UIDs), response_format.Credit cost: Uses daily search quota. No contact credits.

tool

Retrieve a full profile including contact information (emails, phone numbers, social links). Parameters: items (array of UIDs, LinkedIn URLs, or emails), spend_credits_confirmed (boolean), response_format.Credit cost: ⚠️ 1 Contact Credit per successful match.

Company

tool

Look up a company by name, domain, or slug to retrieve its stable numeric ID. Parameters: company_id_or_slug. This tool takes no response_format.Credit cost: Free.

tool

Retrieve comprehensive company data (locations, industries, exact headcount). Parameters: company_id (numeric ID), spend_credits_confirmed (boolean), response_format.Credit cost: ⚠️ 1 Company Credit.

Utility

tool

Check the remaining standard Contact credits for the current API key. Does not include Company credits.Credit cost: Free.

tool

Check the remaining daily quota for profiles retrieved without revealing contact information. Applies to retrieve_person_no_contacts only.Credit cost: Free.

tool

Retrieve the complete list of candidate seniority levels supported by the search API.Credit cost: Free.

tool

Retrieve the complete list of candidate professional departments supported by the search API.Credit cost: Free.

tool

Retrieve the full list of all 146 supported industry categories for the search API.Credit cost: Free.

Searching effectively

Boolean syntax

The text fields — keywords, current_title, current_past_title, current_company, current_past_company — accept boolean expressions:

(Python AND AWS) OR (GCP AND Java)
(Mandarin OR Chinese) AND (Python OR PHP)

Just phrase it naturally in the chat; the assistant passes the expression through. Full syntax reference: Boolean query.

`industry` vs `industries`

Two different filters, easy to confuse:

industry — free-text match on a single industry (e.g. "Software"). Use it when you’re describing the sector in words.
industries — a list of exact industry IDs. Use it when you already know the IDs, from get_available_industries (146 categories).

Why the assistant asks you to pick from a list

When you search by department, level or industry, the assistant is instructed to first fetch the valid options, show them to you, and let you choose — rather than guessing a value that doesn’t exist. That extra step is deliberate and costs nothing. To skip it, name a value from these lists directly.

Departments (15)

Marketing · Sales · Product & Project · Engineering / Development · Data & Analytics · Design / UX · HR & Recruitment · Finance & Accounting · Legal / Compliance · Customer Support / Success · Health, Beauty & Hospitality · Education & Training · Operations & Admin · Facility Services · Entertainment / Production

Seniority levels (11)

Intern / Entry Level · Junior · Mid-Level · Senior · Lead · Head · VP · C-Level · Founder / Owner · Board / Advisory · Directors

Industries are too many to list — ask the assistant for them, or call get_available_industries.

Getting more results: raise `size`, don’t paginate

search_candidates_query takes size up to 100 (default 10). Pagination via scroll_search exists, but the scrollId expires after 15 seconds — too short for a conversational back-and-forth. If you need more results, ask for a bigger batch up front (“find me 50 …”) instead of asking for the next page.

Credits & confirmation

Three separate pools are consumed, and each is reported on its own:

Pool	Spent by	Check with
Daily search quota	`retrieve_person_no_contacts`	`check_without_contacts_credits`
Contact Credits	`retrieve_person_profile`	`check_balance`
Company Credits	`get_company_info`	Not exposed by the API — check your SignalHire account

search_candidates_query and scroll_search do not consume the daily search quota — they use a separate internal quota that is not visible via any utility tool. Their responses still report a remaining balance for it.

The two paid tools (retrieve_person_profile and get_company_info) refuse to run until the assistant passes spend_credits_confirmed=true. The first call therefore always comes back asking for your permission — that’s the intended behaviour, not a failure. Confirm in the chat and the assistant retries; the refusal itself charges nothing.

After a successful charge the remaining balance for that pool is appended to the response, so there’s no need to run a balance check afterwards. To top up, visit signalhire.com/profile/billing.

Company Credits are the exception: there is no tool that reads that balance — check_balance covers Contact Credits only. Check it in your SignalHire account before a run that needs company data.

Example Prompts

Find me 5 Senior Python Developers in London. Show me their skills. Do not fetch their contacts yet.

Uses search_candidates_query → retrieve_person_no_contacts

Reveal the contact information (emails and phone) for that candidate.

Uses retrieve_person_profile

What is the exact headcount and headquarters location of Google? Search for the company ID first.

Uses find_company → get_company_info

Search for engineers with (Python AND AWS) OR (GCP AND Java) experience.

Boolean logic in keywords

Find product managers in London who are open to new opportunities.

Uses the open_to_work filter

Find sales reps with 3 to 5 years of experience in the SaaS industry.

Uses years_experience_from / years_experience_to

Search for marketing directors in Germany, exclude anyone I've already emailed or revealed.

Uses exclude_emailed / exclude_revealed

How many contact credits do I have left? I want to reveal 50 profiles.

Uses check_balance

Troubleshooting

The connector option isn't there at all

Connecting through a chat client’s UI (Claude.ai, Claude Desktop, ChatGPT) requires a paid plan on that client; MCP connectors are not offered on their free tiers. Check your subscription before debugging anything else.This applies to the connector UIs only — the API-key setups on this page (Claude Code, Cursor, Windsurf, VS Code, Codex, n8n, any other MCP client) don’t depend on an AI-client subscription.

Tools don't show up in the client

Client	What to check
Claude.ai	Settings → Connectors → confirm SignalHire is connected and enabled, then refresh the page
Claude Desktop	Restart the app after adding the connector
ChatGPT	Open the tools menu in a chat and confirm the SignalHire tools are listed; reconnect from Settings → Connectors if not
Cursor	Verify `mcp.json` is valid JSON and in the right path, then restart Cursor fully
VS Code	Confirm you’re in Agent mode in Copilot Chat, and check `servers` in `.vscode/mcp.json`
Windsurf	Check the config is saved and the server URL is correct
Codex	Check `~/.codex/config.toml` is valid TOML and that `SIGNALHIRE_API_KEY` is exported in the shell you launched Codex from
n8n	Confirm the MCP Client Tool node is connected to an AI Agent node and the workflow is active; re-check the URL and auth header

The wrong auth header

This server reads the API key only from Authorization: Bearer <key>. A bare key with no Bearer prefix, a different header name (apikey, x-api-key), or the key in the URL as ?token=... are all ignored and come back as 401.

Resource not found when paginating

The scrollId expired (15-second TTL). Run a new search_candidates_query with a larger size (up to 100) instead of paginating.

mcp-remote keeps failing after a config change

It caches per-server state. Clear it and restart the client:

rm -rf ~/.mcp-auth

Make sure Node.js is installed; you can also install the bridge globally with npm i -g mcp-remote.

The assistant asks for permission before revealing contacts

By design — see Credits & confirmation. Say yes and it will retry the same call.

No credits remaining or daily quota exceeded

The relevant pool is empty. Top up the account, or wait for the daily quota to reset; retrying the call will not help.

401 on every call right after connecting, including through OAuth

The account probably has no API key. OAuth carries the key inside the token, so an account that never generated one issues a token with an empty key claim and the server rejects it. Generate the key at signalhire.com/apiIntegrations, then disconnect and reconnect the connector so it picks up a fresh token.

401 Unauthorized

Missing or invalid Authorization: Bearer header, or an expired OAuth token (the client should refresh automatically). Check the header is present and that the key is still active in your API integrations page — generate a new one if it was revoked. A key containing non-ASCII characters (for example a placeholder pasted from a translated guide) is rejected before any request is sent.

The OAuth flow never completes

Disconnect the connector and add it again, and make sure you’re already signed in to SignalHire in the same browser before starting the flow. The flow signs you in to an existing account; it cannot create one.

The balances look wrong, or results aren't the ones I expect

You’re most likely connected under a different SignalHire account than you think. Run check_balance and compare it with the balance shown in the SignalHire web app; if they disagree, disconnect the connector, sign in to the correct account in your browser, and connect again. On the API-key paths, re-copy the key from the right account.With a social login this is the usual cause: the provider silently used a different one of your accounts. Redo the flow, and on the provider’s screen pick the identity your SignalHire account is actually linked to instead of accepting the default.

429 Rate limit exceeded

Too many requests in a short window. Wait a moment and retry; the limit is applied upstream by the SignalHire API, not by this server.

403 Connection Denied

You’re connecting by IP instead of the domain. Always use https://mcp.signalhire.services/mcp — the server filters traffic by the Host header.

TLS / certificate errors

If your client’s CA bundle is out of date, update it (pip install -U certifi for Python). Do not disable TLS verification.

Security

The MCP server is a stateless proxy — your API key is never stored server-side. Each request forwards your credential to the SignalHire API and discards it.
Prefer OAuth (Claude.ai, Claude Desktop, ChatGPT) where it’s available — there’s no key to manage or leak.
Store API keys in a secure credential store — your OS keychain, a password manager, or your editor’s secrets manager. Don’t hardcode them into config files you share.
For team setups, pass the key through an environment variable (as in the Codex config above) instead of committing it to version control. In n8n, use the built-in Credentials system rather than pasting the key into a node field.
Rotate your API key at signalhire.com/apiIntegrations periodically, and immediately if you suspect it has been exposed.
Remove connectors and MCP entries you no longer use, and expose only the tools your use case needs.

​Getting Started

​Step 1 — generate your API key

​Starter prompts

​Connection Details

​Authentication

​Connecting via JSON (API key)

​Which type do I use?

​Claude.ai / Claude Desktop — Custom Connector (OAuth)

​ChatGPT — app directory

​Codex — TOML config (API key)

​n8n — MCP Client Tool node

​Any other MCP client

​Claude Code — CLI

​Python SDK (programmatic)

​Available Tools

​Search & Discovery

​Profile Retrieval

​Company

​Utility

​Searching effectively

​Boolean syntax

​industry vs industries

​Why the assistant asks you to pick from a list

​Getting more results: raise size, don’t paginate

​Credits & confirmation

​Example Prompts

​Troubleshooting

​Security

Getting Started

Step 1 — generate your API key

Starter prompts

Connection Details

Authentication

Connecting via JSON (API key)

Which type do I use?

Claude.ai / Claude Desktop — Custom Connector (OAuth)

ChatGPT — app directory

Codex — TOML config (API key)

n8n — MCP Client Tool node

Any other MCP client

Claude Code — CLI

Python SDK (programmatic)

Available Tools

Search & Discovery

Profile Retrieval

Company

Utility

Searching effectively

Boolean syntax

`industry` vs `industries`

Why the assistant asks you to pick from a list

Getting more results: raise `size`, don’t paginate

Credits & confirmation

Example Prompts

Troubleshooting

Security