CarrierLookup

Model Context Protocol

The CarrierLookup MCP server lets an AI assistant run phone number checks

Connect an MCP-compatible client and it can run single checks, run multi checks on small lists, list available products, and read your balance. No second account or credential is required. Asynchronous bulk tasks are not exposed over MCP because they start from a file upload; use the dashboard or the REST API for those.

Get your API keyView API docs
MCPStreamable HTTP4 tools

01

What is MCP?

The Model Context Protocol lets AI applications call external tools during a conversation. Ask your assistant to look up a phone number or review a batch without writing a separate API integration.

MCP is a protocol adapter. It uses the same products, balance, billing, concurrency limits, timeouts, and result semantics as the REST API.

02

Authentication

Use the exact same API key as the REST API and add it as a Bearer token in your MCP client configuration.

Authorization header
Authorization: Bearer YOUR_API_KEY
Keep your API key privateOnly add the key to your own trusted client configuration. Never expose it in browser code or public prompts.

03

Server URL

Point your client to the official Streamable HTTP endpoint. No local MCP process is required.

MCP endpointStreamable HTTP
https://carrierlookup.online/mcp

Requests use JSON-RPC over Streamable HTTP and the same API-key middleware as REST.

04

Connect your client

Choose the configuration format your client supports. Replace the placeholder with your API key.

Claude Code

Add the remote server from your terminal.

claude mcp add --transport http carrierlookup https://carrierlookup.online/mcp --header "Authorization: Bearer YOUR_API_KEY"

Cursor / Claude Desktop

Add this server entry to the client's MCP configuration.

{
  "mcpServers": {
    "carrierlookup": {
      "url": "https://carrierlookup.online/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Other MCP clients

Use Streamable HTTP with the endpoint and Bearer header above.

URL: https://carrierlookup.online/mcp
Authorization: Bearer YOUR_API_KEY

05

Available tools

The tools are scoped to the app that owns your API key. Call list_products first when you need to discover valid product codes.

list_products

Lists products, prices, billing multipliers, and response fields.

No parameters

check_number

Looks up one phone number synchronously. The extra object is the primary result.

service_type · string · required
identifier · string · required

check_numbers

Checks 1–100 phone numbers with one service_type and preserves input order.

service_type · string · required
identifiers · string[] · required · max 100

get_balance

Reads the current account balance without charging it.

No parameters

06

Example prompts

After connecting, ask your assistant in plain language:

  • “Look up which carrier +14155552671 was originally allocated to.”
  • “Check these 20 phone numbers and summarize the results.”
  • “How much balance is left before I run this batch?”

07

Error handling

Tool failures use isError=true and the same code, msg, data contract as the API.

Example tool error
{
  "code": 42901,
  "msg": "too many concurrent requests",
  "data": null
}
40000

Invalid product or field

Unsupported service_type or conflicting fields.

40002

Invalid phone number

The submitted phone number is not a valid format.

40100

Missing or invalid API key

Check the Bearer header and confirm the key is active.

40200

Insufficient balance

The request is rejected before processing when the full batch amount cannot be covered.

42200

Undetermined

The phone number could not be determined at this time. No result is returned, and this call is not charged.

42901

Concurrency budget full

All five in-flight request slots are busy, or a multi check is already running on this account. Not charged; retry once one finishes.

50303

Service at capacity

Too many checks are in progress platform-wide. Not charged; wait for the Retry-After seconds and resubmit.

50400

Check timed out

Did not finish in time. Not charged; a timed-out multi check fails as a whole and is refunded in full.

50300

Service maintenance

Retry later.

Ready to connect your AI assistant?

Create an account, copy your API key, and start checking from your preferred MCP client.

Create a free account View REST API docs