> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jojapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use APIs from AI agents (MCP)

> Every API on the JoJ API marketplace is also an MCP server. Connect Claude Code, Cursor, VS Code or any MCP client and call endpoints with your JoJ API key.

Every API on the JoJ API marketplace is also a **Model Context Protocol (MCP) server**. Connect one to your AI agent and every documented endpoint becomes a tool the agent can discover and call — authenticated with your regular JoJ API key, billed to your regular subscription.

## Server URLs

| Server                                           | URL                                 | Auth                                       |
| ------------------------------------------------ | ----------------------------------- | ------------------------------------------ |
| One specific API (every endpoint as a tool)      | `https://mcp.jojapi.com/{api-slug}` | JoJ API key for calls; tool list is public |
| Marketplace discovery (search the whole catalog) | `https://mcp.jojapi.com`            | JoJ API key only for `call_endpoint`       |

The `{api-slug}` is the last segment of an API's marketplace URL — for `jojapi.com/hub/api/web-search` it is `web-search`. You can also copy ready-made snippets from the **Connect** button on any API page. The path-based aliases `https://jojapi.com/mcp` and `https://jojapi.com/mcp/{api-slug}` serve the same servers and keep working.

Both servers speak MCP over **Streamable HTTP** (stateless, JSON-RPC over POST). Server-push SSE streams are not used.

## Authentication

Send your JoJ API key as an HTTP header on the MCP connection — the same key and the same [accepted shapes](/consumers/api-keys) as any other JoJ API call:

```
Authorization: Bearer jk_...
```

`X-JoJAPI-Key: jk_...`, `Authorization: jk_...` and Basic (key as username or password) work too. Keys never appear in tool arguments or URLs. Without a key the servers still connect and list tools — calls return instructions for getting one.

<Warning>
  The key in your MCP configuration is a live credential. Treat the config file like a password store, and consider a [key restricted to just that API](/consumers/api-keys).
</Warning>

## Connect from popular clients

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http joj-web-search https://mcp.jojapi.com/web-search --header "Authorization: Bearer jk_..."
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

    ```json theme={null}
    {
      "mcpServers": {
        "joj-web-search": {
          "url": "https://mcp.jojapi.com/web-search",
          "headers": { "Authorization": "Bearer jk_..." }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "joj-web-search": {
          "type": "http",
          "url": "https://mcp.jojapi.com/web-search",
          "headers": { "Authorization": "Bearer jk_..." }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude.ai">
    Settings → Connectors → **Add custom connector**, then paste the server URL. Header-based authentication for custom connectors is currently rolling out in beta on claude.ai; Claude Code supports headers everywhere.
  </Tab>
</Tabs>

Any other MCP client that supports Streamable HTTP with custom headers works the same way.

## The discovery server

`https://mcp.jojapi.com` exposes four tools over the whole catalog:

| Tool            | What it does                                  | Key needed |
| --------------- | --------------------------------------------- | ---------- |
| `search_apis`   | Search APIs by name/description               | No         |
| `get_api`       | One API's overview, endpoint list and links   | No         |
| `get_endpoint`  | Full parameter/response docs for one endpoint | No         |
| `call_endpoint` | Execute an endpoint through the gateway       | Yes        |

It is handy as a single always-on connector: the agent finds an API, reads its docs and calls it without you wiring a new server per API.

## Billing, limits and errors

* A tool call **is** a gateway call: the same [plans and quotas](/consumers/managing-subscriptions), the same [rate limits](/gateway/rate-limits), the same [usage response headers](/consumers/response-headers). Each tool result ends with a `usage —` line summarizing what the call consumed.
* Tool descriptions include each endpoint's billing (fixed amounts, or last-month averages for metered objects).
* Gateway errors come back as readable tool errors with the fix linked — e.g. a `402` explains whether the plan lacks the object, the quota ran out, or the pay-as-you-go balance is low.
* Responses larger than **50,000 characters** are truncated (with a note) to protect the agent's context window. Calls time out after **95 seconds**.
* Event-stream (SSE) endpoints are delivered buffered, after the stream completes.

## Notes

* The tool list mirrors the API's public documentation and refreshes within \~5 minutes of a provider's change. Tool names match the `operationId`s in the API's [OpenAPI spec](https://jojapi.com/hub/api/web-search/openapi.json) (`get_v1_search`, `post_report`, …).
* API responses pass through from providers unmodified. Treat them as data — your agent should not follow instructions found inside API responses.