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

# MCP quickstart

> Create an MCP-scoped API key, connect your client to the Titan MCP server, and make your first agent tool call.

This takes about five minutes. At the end your agent can search the web and read pages through Titan.

## Before you begin

| Requirement              | Why                                                                               |
| ------------------------ | --------------------------------------------------------------------------------- |
| A Titan account          | API keys are created against your user identity                                   |
| An MCP-compatible client | Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, or your own agent runtime |
| Credits on your plan     | Tool calls draw from your wallet; the free plan includes an allowance             |

<Steps>
  <Step title="Create an MCP-scoped API key">
    Get a JWT by signing in, then create a key carrying the five MCP scopes:

    ```bash theme={null}
    curl -sS -X POST "$AUTH_URL/api/v1/api-keys" \
      -H "Authorization: Bearer $JWT_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Agent MCP key",
        "scopes": [
          "mcp:search",
          "mcp:fetch",
          "mcp:crawl",
          "mcp:templates:run",
          "mcp:runs:read"
        ]
      }'
    ```

    Copy the `key` value from the response. It starts with `titan_sk_` and is shown only once.

    ```bash theme={null}
    export TITAN_API_KEY="titan_sk_..."
    ```

    <Note>
      Only grant the scopes your agent actually needs. A research agent that never crawls does not need `mcp:crawl`. See [Authentication and scopes](/docs/mcp/authentication-and-scopes).
    </Note>
  </Step>

  <Step title="Connect your client">
    Point your client at the hosted endpoint with your key in an `Authorization` header.

    <Tabs>
      <Tab title="Claude Code">
        ```bash theme={null}
        claude mcp add --transport http titan https://mcp.webscraping.titannet.io/mcp \
          --header "Authorization: Bearer $TITAN_API_KEY"
        ```
      </Tab>

      <Tab title="Cursor">
        Add to `~/.cursor/mcp.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "titan": {
              "url": "https://mcp.webscraping.titannet.io/mcp",
              "headers": {
                "Authorization": "Bearer titan_sk_..."
              }
            }
          }
        }
        ```
      </Tab>

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

        ```json theme={null}
        {
          "servers": {
            "titan": {
              "type": "http",
              "url": "https://mcp.webscraping.titannet.io/mcp",
              "headers": {
                "Authorization": "Bearer titan_sk_..."
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Windsurf">
        Add to `~/.codeium/windsurf/mcp_config.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "titan": {
              "serverUrl": "https://mcp.webscraping.titannet.io/mcp",
              "headers": {
                "Authorization": "Bearer titan_sk_..."
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    Other clients are covered in [Connect your client](/docs/mcp/connect-your-client).
  </Step>

  <Step title="Confirm the tools are available">
    Restart or reload your client, then ask it what Titan tools it can see. You should get six: `titan_search`, `titan_fetch`, `titan_crawl`, `titan_list_templates`, `titan_run_template`, and `titan_get_run`.

    To check the connection without a client:

    ```bash theme={null}
    curl -sS -X POST "https://mcp.webscraping.titannet.io/mcp" \
      -H "Authorization: Bearer $TITAN_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list"
      }'
    ```
  </Step>

  <Step title="Make your first call">
    Ask your agent something that needs the live web:

    > Search for the three most recent posts about WebAssembly performance, then read them and summarize what changed.

    The agent calls `titan_search` to discover URLs, then `titan_fetch` on the ones it picks. You can also drive it directly:

    ```bash theme={null}
    curl -sS -X POST "https://mcp.webscraping.titannet.io/mcp" \
      -H "Authorization: Bearer $TITAN_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": {
          "name": "titan_search",
          "arguments": {
            "query": "webassembly performance benchmarks",
            "search_provider": "brave",
            "max_results": 5,
            "freshness": "month"
          }
        }
      }'
    ```
  </Step>
</Steps>

## What comes back

Every tool returns a consistent envelope:

```json theme={null}
{
  "run_id": "9f1c2e84-5b3a-4d7e-8c19-2a6f0b4d7e31",
  "status": "completed",
  "results": [
    {
      "url": "https://example.com/wasm-benchmarks",
      "title": "WebAssembly performance in 2026",
      "snippet": "Benchmarks across four runtimes...",
      "rank": 1,
      "search_provider": "brave",
      "result_type": "organic",
      "retrieved_at": "2026-07-27T09:14:22Z"
    }
  ],
  "usage": {
    "billing_unit": "successful_delivery",
    "records_returned": 5,
    "credits_estimated": 1,
    "billing_status": "billable"
  },
  "warnings": [],
  "request_id": "req_8f3a1c9e2b7d4056"
}
```

`run_id` is the Titan `execution_id`. You can look the same run up through the [Task Service API](/docs/use-the-platform/use-the-task-service-api) or in the dashboard.

## Next steps

<CardGroup cols={2}>
  <Card title="Tool reference" icon="wrench" href="/docs/mcp/tools/overview">
    Every parameter, default, and limit for the six tools.
  </Card>

  <Card title="Build a research agent" icon="robot" href="/docs/mcp/examples/research-agent">
    A worked search-then-fetch pipeline with prompts and tool calls.
  </Card>

  <Card title="Runs and results" icon="clock" href="/docs/mcp/runs-and-results">
    Synchronous vs asynchronous runs, statuses, and polling.
  </Card>

  <Card title="Credits and usage" icon="coins" href="/docs/mcp/credits-and-usage">
    What each tool costs and what is free.
  </Card>
</CardGroup>