Copy page

Remote MCP server

Remote MCP server

Tomba hosts a Model Context Protocol (MCP) server that lets AI assistants find and verify email addresses, look up phone numbers, enrich people and companies, and manage leads. You connect a client to one URL; there's nothing to install.

Endpoint

The server exposes 28 tools, 12 prompts, and 3 resources, listed in Tools, prompts, and resources. Connect a client has the setup for each assistant. To run a server on your own machine instead, see Local MCP server.

How it works

Each tool call becomes one request to the Tomba API (https://api.tomba.io/v1), made with your credentials. The server forwards the credentials with that request and keeps no state between requests.

Authentication

The server accepts three kinds of credentials, each identifying a Tomba account.

When a request carries none of them, the server answers 401 with the header WWW-Authenticate: Bearer resource_metadata="https://mcp.tomba.io/.well-known/oauth-protected-resource" and the JSON-RPC error -32001 (Authentication required). The server doesn't check a key and secret when the client connects: wrong values show up as an error on the first tool call.

OAuth 2.0

Clients that support MCP authorization read the metadata URL from the 401, open a browser window where you sign in to Tomba and approve access, and then send the access token with every request. You don't handle keys. The authorization server is https://api.tomba.io; its endpoints, scopes, and token lifetimes are listed under OAuth 2.0.

• Each tool needs the scope of the API endpoint it calls; Tools, prompts, and resources lists the endpoint of every tool.
• usage_info and get_logs call endpoints that don't accept OAuth tokens. They fail under OAuth; use a key and secret for them.
• Review or revoke access under Connected apps in the dashboard.

API key as a bearer token

For clients that can send an Authorization header but not custom headers, encode your key and secret, separated by a colon, in base64. Remove line breaks, which base64 adds to long input on Linux:

Code
printf '%s' "$TOMBA_API_KEY:$TOMBA_SECRET_KEY" | base64 | tr -d '\n'

Send the result as Authorization: Bearer <result>. To check the token, list the tools:

Code
TOKEN=$(printf '%s' "$TOMBA_API_KEY:$TOMBA_SECRET_KEY" | base64 | tr -d '\n')
curl -X POST "https://mcp.tomba.io/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The response is a server-sent event whose data line holds the JSON-RPC result with 28 tools.

API key headers

Send your key and secret in the same headers as the Tomba API:

Code
X-Tomba-Key: ta_xxxx
X-Tomba-Secret: ts_xxxx

If a request also carries an Authorization: Bearer header, the server uses that header instead.

Limits and billing

• A tool call is billed like the API request it makes, against your plan's credits: see Credit costs.
• Tool calls count toward your plan's rate limits. The server has no limit of its own and doesn't pass rate limit headers to the client; see Check your limits for the current values.
• When the Tomba API answers 429 or a 5xx status, the server tries the request up to 3 times in total, waiting 1 second and then 2 seconds between attempts. Each attempt times out after 120 seconds, and a timed-out attempt isn't retried.

Errors