Agents & MCP

Krawl is built to be driven by autonomous agents, not just humans. There are three ways an agent can call it, plus a full discovery surface so an agent can find and pay for it on its own.

• MCP server — connect Krawl as a Model Context Protocol tool (Claude, Cursor, ChatGPT, Smithery, mcp.so).
• OpenAI-compatible shim — point any OpenAI SDK at Krawl and get a cited report back.
• Native HTTP + SSE — the research API directly.

Authentication on all three is the same: an API key, a no-signup demo key, or keyless x402 payments.

MCP ServerCopy Anchor Link

Krawl exposes a Model Context Protocol server at POST /mcp using the Streamable HTTP transport (JSON-RPC 2.0 over a single POST).

• Default protocol version: 2025-06-18
• Server: krawl v0.2.0
• Methods: initialize, ping, tools/list, tools/call

Discovery methods (initialize, ping, tools/list) are never gated, so an agent platform can connect and enumerate tools without credentials. Only tools/call execution is authenticated, mirroring the research endpoints (X-API-Key, or keyless x402 when enabled).

ToolsCopy Anchor Link

Each tool advertises its input schema and (where applicable) an x402 price (USDC atomic units) on tools/list. Per-tool x402 means an agent can shop the catalog before signing a payment.

Free tools are read-only; paid tools advertise price in the tools/list response so an agent can budget. Without a key, tools/call on a paid tool returns 402 with an x402 challenge.

Protocol compatibilityCopy Anchor Link

Legacy clients continue to call initialize. It returns 2025-06-18, including when the client requests a later version through that handshake. GET discovery and the existing legacy SSE endpoint remain available.

An experimental 2026-07-28 transport is implemented behind MCP_MODERN_ENABLED=false. Keep it disabled in deployments until the modern authorization and reference-client acceptance in issue #120 pass. When enabled, each POST carries its version, client identity and capabilities in params._meta; no initialization or session identifier is required. server/discover advertises the enabled versions. Supply MCP-Protocol-Version, Mcp-Method and, for named operations, Mcp-Name matching the body. Accept both JSON and event streams. Modern successful results include resultType: "complete"; discovery, lists and resource reads include cache hints. Private resource reads are scoped to the authenticated caller and marked private with zero TTL.

The experimental transport reuses Krawl's existing API-key/x402 authorization, quota and metering. This is not a completed OAuth 2.1 migration: resource indicators, issuer/audience validation, modern 401/403 challenges, client metadata registration and live Registry installation still need acceptance. Krawl does not advertise support for subscriptions, Tasks or multi-round-trip requests. The MCP specification defines those separate capabilities.

Install in Claude CodeCopy Anchor Link

The skill installs research instructions and a bundled shell client. Configure MCP separately in the next section. Repository installation currently requires GitHub read access because the source repository is private.

npx skills@1.7.4 add ravidsrk/krawl --skill krawl --agent claude-code

From an existing checkout, use npx skills@1.7.4 add ./skills/krawl --skill krawl --agent claude-code --copy --yes. The canonical skill directory includes its scripts and reference files. Public distribution remains a release step; packaging alone does not configure MCP or validate a live query.

ConnectCopy Anchor Link

Add Krawl as an MCP server in your agent platform:

{
  "mcpServers": {
    "krawl": {
      "url": "https://api.krawl.sh/mcp",
      "headers": { "X-API-Key": "krawl_live_…" }
    }
  }
}

A GET /mcp returns a friendly capability pointer (server name, version, protocol, transport, and tool names) for probes that hit it with the wrong method.

Raw JSON-RPCCopy Anchor Link

# List tools (no credentials required)
curl -X POST https://api.krawl.sh/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call a tool (authenticated, or keyless via x402)
curl -X POST https://api.krawl.sh/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: krawl_live_…" \
  -d '{
    "jsonrpc":"2.0","id":2,"method":"tools/call",
    "params":{"name":"quick_search","arguments":{"query":"What is EIP-4844?"}}
  }'

A tools/call drains the research SSE stream to completion and returns a single text result.

OpenAI-Compatible ShimCopy Anchor Link

Point any OpenAI client (or LangChain, LlamaIndex, etc.) at Krawl by setting base_url. The model selects the research mode; the last user message is the research query. The assistant message is a fully-cited report. Both streaming and non-streaming are supported.

Endpoints: POST /v1/chat/completions (and /chat/completions), GET /v1/models (and /models).

ModelsCopy Anchor Link

Each research mode maps to a krawl-* model id:

Example (Python)Copy Anchor Link

from openai import OpenAI

client = OpenAI(
    base_url="https://api.krawl.sh/v1",
    api_key="krawl_live_…",
)

resp = client.chat.completions.create(
    model="krawl-deep",
    messages=[{"role": "user", "content": "What is the state of AI agents?"}],
)
print(resp.choices[0].message.content)  # cited markdown report

Example (curl)Copy Anchor Link

curl -X POST https://api.krawl.sh/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: krawl_live_…" \
  -d '{
    "model": "krawl-quick",
    "messages": [{"role": "user", "content": "What is EIP-4844?"}],
    "stream": false
  }'

When a request is paid via x402, the settlement receipt is returned in the X-PAYMENT-RESPONSE header. See Payments & x402.

DiscoveryCopy Anchor Link

Krawl publishes machine-readable descriptors so an agent can find, understand, and pay for it without a human.

Resource discoveryCopy Anchor Link

GET /discovery/resources lets an agent learn what costs what before triggering a 402:

{
  "x402Version": 1,
  "enabled": true,
  "facilitator": "https://x402.org/facilitator",
  "resources": [
    {
      "resource": "https://api.krawl.sh/research",
      "method": "POST",
      "description": "Deep multi-source research report (cited markdown).",
      "x402": {
        "scheme": "exact",
        "network": "base",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "maxAmountRequired": "5000000",
        "priceUsd": 5.0,
        "payTo": "0x…"
      }
    }
  ],
  "payment_methods": ["x402", "api_key"],
  "auth_docs": "https://krawl.sh/auth.md"
}

Next StepsCopy Anchor Link

• Authentication — API keys, demo keys, plans, and quotas
• Payments & x402 — keyless per-request agent payments
• API Reference — every endpoint and schema
• Research Modes — what each krawl-* model does