Endpoint

The hosted server listens at a single URL. Every JSON-RPC request — initialize, notifications, tools/list, tools/call — uses POST. GET on the same path is reserved for the streamable-HTTP listening channel and the MCP client manages it for you.

https://mcp.datpaq.com/

Health check is exposed separately at https://mcp.datpaq.com/healthz — see the Health check section.

Authentication

Every request must present a Datpaq API key as a Bearer token. Requests without a valid header are rejected with HTTP 401 and a WWW-Authenticate: Bearer response header. The hosted server does not pre-validate keys against the Datpaq API; an invalid key returns 401 from the API on the first tool call, surfaced back to the client as an MCP isError result.

Authorization: Bearer YOUR_DATPAQ_API_KEY
Content-Type:  application/json
Accept:        application/json, text/event-stream
Mcp-Session-Id: <returned by initialize>   # on every call after the handshake

Keys are never stored, logged, or shared. Calls bill against your existing Datpaq plan with the same rate limits as the direct API. Grab a key from the dashboard.

Transport

Streamable HTTP, MCP protocol version 2024-11-05. JSON-RPC 2.0 envelopes carried over standard POST requests with optional chunked responses — no SSE-only quirks. Compatible with any HTTP/1.1 or HTTP/2 client and transparent to typical corporate proxies.

JSON-RPC handshake

Three messages establish a session: initialize → notifications/initialized → first useful request. The client picks its own request IDs; the server picks the session ID.

1. initialize

POST https://mcp.datpaq.com/
Authorization: Bearer YOUR_DATPAQ_API_KEY
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "your-client", "version": "1.0.0" }
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Mcp-Session-Id: mcp-session-c0e20c7f-a7c5-4384-b085-7778b4fb8e68

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "Datpaq Proapi", "version": "1.0.0" }
  }
}

2. notifications/initialized

No id, no expected response. Notifications use the same envelope but are fire-and-forget.

POST https://mcp.datpaq.com/
Authorization: Bearer YOUR_DATPAQ_API_KEY
Mcp-Session-Id: mcp-session-...
Content-Type: application/json

{ "jsonrpc": "2.0", "method": "notifications/initialized", "params": {} }

tools/list

Enumerates the available tool catalog. On the hosted surface this is 34 tools across 13 active Datpaq interfaces. Each tool ships a JSON Schema for its arguments and a set of MCP behavior hints (readOnlyHint, destructiveHint, openWorldHint).

Request

POST https://mcp.datpaq.com/
Authorization: Bearer YOUR_DATPAQ_API_KEY
Mcp-Session-Id: mcp-session-...
Content-Type: application/json
Accept: application/json, text/event-stream

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

Response (abbreviated)

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "whois_lookup",
        "description": "Look up domain registration ...",
        "inputSchema": {
          "type": "object",
          "properties": {
            "domain": { "type": "string", "description": "..." }
          },
          "required": ["domain"]
        },
        "annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "openWorldHint": true
        }
      }
      // ... 33 more tools across the 13 active interfaces
    ]
  }
}

tools/call

Invokes a single tool with structured arguments matching its inputSchema. The hosted server constructs a per-request client from your Bearer token, drives the underlying API call, and returns the result in MCP content shape. The on-disk response cache is disabled per request so multi-step workflows (e.g. delete-then-read) never see a stale snapshot.

Request

POST https://mcp.datpaq.com/
Authorization: Bearer YOUR_DATPAQ_API_KEY
Mcp-Session-Id: mcp-session-...
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "whois_lookup",
    "arguments": { "domain": "example.com" }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "{\"domain\":\"example.com\",\"registrar\":\"...\"}" }
    ]
  }
}

On failure the result has isError: true and a content[0].text string starting with an English summary (e.g. authentication failed: ...) and a hint pointing at next steps.

Session management

The server returns an Mcp-Session-Id response header on initialize. Echo that value as a request header on every subsequent request from the same client. Each tool call is otherwise stateless — the session is a logical client identifier, not a per-user lock or auth state.

Sessions are reaped after a period of inactivity. If a request fails with 404 session not found, repeat the initialize handshake. Mature MCP clients do this transparently.

Tool naming convention

Tool names follow {interface-slug}_{action}, where the slug is one of the active Datpaq interfaces and the action describes the operation. Slugs use hyphen-case internally; the underscore between slug and action is the only underscore in the name.

whois_lookup
ip-geolocation_get
image-processing_image-resize
working-days_calculate-get

The hosted surface only exposes tools for the active interfaces below. The local stdio server (bundled with the CLI) also exposes a curated set of framework tools — search, sql, context — and a cobra-tree mirror that shells out to the sibling CLI binary. Those tools are intentionally omitted from the hosted surface.

Active interfaces

Each active interface contributes one or more tools. Click through for per- endpoint detail in the regular Datpaq API docs — the parameters and response shapes are identical whether you call from the CLI, the direct API, or MCP.

Errors

Two error layers: HTTP status codes at the transport boundary, and MCP isError: true results inside successful (HTTP 200) JSON-RPC envelopes. Auth failures at the transport layer return real HTTP 401s; everything past the handshake is wrapped in JSON-RPC.

Health check

Unauthenticated GET /healthz returns 200 OK with {"ok":true} when the server is up. Suitable for load-balancer probes and uptime monitors. The MCP endpoint itself does not respond to unauthenticated GETs by design.

curl -s https://mcp.datpaq.com/healthz

Local stdio variant

The Datpaq CLI bundles datpaq-mcp, a sibling binary that speaks the same MCP protocol over stdio against your local config file. Useful for offline development and when you want the agent to call framework tools (search, sql) against your locally-synced data.

See the CLI reference's MCP server section for install and Claude Desktop config of the stdio variant.