Connect AI agents to Zephira

Six company-data tools

Coverage varies by company and jurisdiction. Preserve source and modelled-data labels when displaying results. Missing data does not prove that a fact does not exist.

Search first, then retrieve a company

Call search_entities with a location and at least one of name, registration_number, vat_number or ticker.

{
  "name": "search_entities",
  "arguments": {
    "location": "GB",
    "name": "Tesco",
    "include_provenance": true
  }
}

Use a numeric company ID returned by the search as a string in entity_id. The ID below is illustrative; replace it with your search result.

{
  "name": "get_entity",
  "arguments": {
    "entity_id": "123",
    "include_provenance": true
  }
}

All retrieval tools accept entity_id and optional include_provenance (default true). Officers and shareholders also accept page (default 1) and per_page (default 10, maximum 50). Search accepts an optional city_or_state array.

Successful tool results provide the API payload under data, with meta.request_id, meta.status, meta.units and meta.remaining_units. Results are available as both text and structured content.

Protocol and client compatibility

The endpoint supports MCP 2026-07-28 and the stateless legacy Streamable HTTP flow. Current clients use server/discover; older clients use initialize, followed by notifications/initialized. Both can then use tools/list and tools/call.

For a direct request using the current protocol, include the per-request metadata and matching HTTP headers. MCP client libraries normally supply these automatically.

curl https://dashboard.zephira.ai/api/mcp \
  -H "Authorization: Bearer $ZEPHIRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": {
          "name": "my-client", "version": "1.0.0"
        },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

For tools/call, set Mcp-Method: tools/call, add Mcp-Name matching the tool name, and include name and arguments beside _meta in params. Discovery and tool listing do not consume data credits.

This endpoint provides tools. It does not provide prompts or resources, and does not require a persistent session ID. Modern replies use JSON; legacy clients must also accept text/event-stream.

Usage and troubleshooting

Successful data calls consume one unit from the same workspace allowance as the dashboard API. API-key scopes, revocation and allowance limits apply to every tool call. Failed data requests are not charged.

Tool execution failures return isError: true, an error object and request metadata inside the MCP result. Use the request ID when contacting support.

REST API reference · Contact support