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.

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 handling	Claude.ai / Claude Desktop connector UI

OAuth details. OAuth is handled by SignalHire’s Auth0 authorization server (https://signalhire.eu.auth0.com/). When you add the connector, Claude discovers the authorization server via RFC 9728 metadata, you log in and consent on the SignalHire/Auth0 screen, and Claude receives a token — no API key is entered by hand. Expired tokens return 401 and Claude 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.

{
    "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`	Omit the `"type"` field
Windsurf	`~/.codeium/windsurf/mcp_config.json`	Rename `"url"` → `"serverUrl"`
VS Code (Copilot agent mode)	`.vscode/mcp.json`	Rename `"mcpServers"` → `"servers"`

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)

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.

Claude Code — CLI

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

Python SDK (programmatic)

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)

Available Tools

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

Response format: every tool accepts a response_format parameter (default "markdown"); set it to "csv" or "json" as needed.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, 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 searches and profiles retrieved without revealing contact information.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.

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

Troubleshooting

mcp-remote keeps failing after a config change

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

rm -rf ~/.mcp-auth

401 Unauthorized

Missing or invalid Authorization: Bearer header, or an expired OAuth token (the client should refresh automatically). Check the header is present and the SignalHire API key is valid.

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.

​Connection Details

​Authentication

​Connecting via JSON (API key)

​Which type do I use?

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

​Claude Code — CLI

​Python SDK (programmatic)

​Available Tools

​Search & Discovery

​Profile Retrieval

​Company

​Utility

​Example Prompts

​Troubleshooting

Connection Details

Authentication

Connecting via JSON (API key)

Which type do I use?

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

Claude Code — CLI

Python SDK (programmatic)

Available Tools

Search & Discovery

Profile Retrieval

Company

Utility

Example Prompts

Troubleshooting