# Connect KeepBal with MCP

Endpoint: https://keepbal.com/mcp. Streamable HTTP with JSON responses; no SSE or session ID required. Initialize and list tools without a key. All tool calls require Authorization: Bearer dgk_live_...; create your key in Console. Keep keys private.

Discovery: /server.json follows its versioned MCP Registry schema. /.well-known/mcp.json and /.well-known/mcp/server-card.json describe this MCP service. /.well-known/agent-card.json uses the KeepBal keepbal-agent-discovery-v1 contract: name, description, version, provider, status, capabilities and skills with id, name, description, tags and transport. Its discovery_stub status means A2A transport is not live; use the advertised MCP or REST routes.

search_tools searches live tools and models locally with a query of 2–200 characters, limit 1–25 and offset pagination. inspect_tool reads known local parameters; unknown schemas are marked. Both are free. get_run {run_id} checks and settles an existing run without a new execution or polling fee. run_tool uses the same prepaid wallet, access controls and settlement as REST. Provider failures are not charged. Pending runs are polled for up to 25 seconds; check later with get_run. Results over 48,000 characters are truncated with cost and a do-not-retry notice. Unsupported downloads also return a do-not-retry notice. Models are listed for discovery and called through their documented REST endpoints.

## Claude Code

```sh
claude mcp add --transport http keepbal https://keepbal.com/mcp --header "Authorization: Bearer $KEEPBAL_API_KEY"
```

## Cursor

Add this to ~/.cursor/mcp.json. Replace YOUR_KEEPBAL_API_KEY with your key; this example uses a literal header value.

```json
{
  "mcpServers": {
    "keepbal": {
      "url": "https://keepbal.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEEPBAL_API_KEY"
      }
    }
  }
}
```

## Claude Desktop: stdio bridge

For a client configured with local stdio servers, use the mcp-remote bridge (requires Node.js and npx). Add the following to your Desktop MCP configuration, replacing YOUR_KEEPBAL_API_KEY. This is a bridge-based setup.

```json
{
  "mcpServers": {
    "keepbal": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://keepbal.com/mcp",
        "--header",
        "Authorization:${KEEPBAL_AUTH}"
      ],
      "env": {
        "KEEPBAL_AUTH": "Bearer YOUR_KEEPBAL_KEY"
      }
    }
  }
}
```

## Codex CLI

Export KEEPBAL_API_KEY in the environment that launches Codex, then add this to ~/.codex/config.toml:

```toml
[mcp_servers.keepbal]
url = "https://keepbal.com/mcp"
bearer_token_env_var = "KEEPBAL_API_KEY"
```

[Codex MCP configuration reference](https://developers.openai.com/codex/mcp)

## Generic Streamable HTTP client

Set the server URL and Authorization bearer header. POST JSON-RPC 2.0 with Content-Type: application/json and Accept: application/json, text/event-stream. Initialize with protocolVersion 2025-06-18 (2025-03-26 also accepted), capabilities and clientInfo, then send notifications/initialized. Notifications return HTTP 202. Send one request per POST; batches are rejected. Protocol GET requests return 405; browser HTML requests show endpoint help.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_tools",
    "arguments": {
      "query": "web search",
      "limit": 5
    }
  }
}
```

[Get a key](https://keepbal.com/console) · [Top up](https://keepbal.com/console/wallet)

[Docs](/docs)

[Quickstart](/docs/quickstart) · [Authentication](/docs/authentication) · [Billing](/docs/billing) · [Tools](/docs/tools) · [Models](/docs/models) · [MCP](/docs/mcp) · [Errors](/docs/errors) · [Rate limits and budgets](/docs/rate-limits-and-budgets)

[Previous: Models](/docs/models) · [Next: Errors](/docs/errors)