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

# Run a headless agent with an API token

> A hands-on MCP Manager lesson for developers: create a token-based host in Apps & Agents, generate an API access token scoped to a gateway, call a tool over HTTP with an Authorization: Bearer token, and confirm the call is attributed and logged.

Not every agent has a browser. CI jobs, cron tasks, and backend services need to reach a gateway with a credential they can carry in code — not an interactive OAuth flow. This tutorial does exactly that: you'll create a token-based host in **MCP Manager**, generate an API access token scoped to one gateway, call a tool over HTTP with a bearer token, and confirm the call is governed and logged just like an interactive one. The payoff is real automation that's still fully attributable.

<Info>
  This tutorial uses **Create and manage API tokens**. If [Apps & Agents](https://app.mcpmanager.ai/settings/hosts) won't let you create a host or generate a token, your role lacks that capability — access depends on the capability, not on a role name. See the [capabilities reference](/deployment/rbac-and-roles/capabilities).
</Info>

## What you'll need

* A gateway with at least one tool, that you can reach. The **Quickstart** gateway from [Your first governed tool call](/tutorials/first-tool-call) works.
* A terminal with `curl`.
* About 10 minutes.

## Headed apps versus headless agents

An interactive client (Claude, Cursor) authorizes through the browser and carries a user's OAuth session. A **headless** agent can't do that, so MCP Manager gives it a **token-based host**: a host that authenticates with a long-lived API access token instead of an interactive login. The host is the identity of your automation; the token is its credential; both are governed by the same gateways, rules, and logs as everything else.

## Step 1: Create a token-based host

<Steps>
  <Step title="Open Apps & Agents">
    Go to [Apps & Agents](https://app.mcpmanager.ai/settings/hosts) and click **Add API access token-based host**.
  </Step>

  <Step title="Name the host">
    Set **Host name** to something that identifies the automation — for example `CI bot` — and save. This host now represents your agent everywhere in MCP Manager: in logs, in policies, and in access reviews.
  </Step>
</Steps>

## Step 2: Generate an API access token

<Steps>
  <Step title="Start the token flow">
    From the host, go to the **Connections** tab. Then click **Add a connection**. A new tab will open for the token generation flow.
  </Step>

  <Step title="Pick the gateway">
    Choose the gateway this token should reach (for example, **Quickstart**), then click **Next** or **Allow**. Follow the steps from there to authenticate, if necessary, with any of the assigned servers in that gateway. The token is scoped to that one host-and-gateway pairing.
  </Step>

  <Step title="Copy the token and gateway URL">
    You'll land on **Your API access token is ready.** Copy both the **Gateway URL** and the **API access token** (or use **Download as CSV**). The token starts with `API_`.

    <Warning>
      The screen warns: **Save this token in a secure location. It will not be viewable again after this page is closed. Treat it like a password.** Store it in a secret manager or your CI's encrypted secrets — never in source control. The token does not expire on its own; you revoke it by deleting its connection (see Step 4).
    </Warning>
  </Step>
</Steps>

## Step 3: Call a tool over HTTP

The gateway speaks MCP over streamable HTTP using JSON-RPC. Present the token as a bearer credential in the `Authorization` header. Substitute your copied **Gateway URL** and **API access token** for the placeholders below.

<CodeGroup>
  ```bash List available tools theme={null}
  curl -X POST '<your-gateway-url>' \
    -H 'Authorization: Bearer <your-api-access-token>' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  ```

  ```bash Call a tool theme={null}
  curl -X POST '<your-gateway-url>' \
    -H 'Authorization: Bearer <your-api-access-token>' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"<tool-name>","arguments":{}}}'
  ```
</CodeGroup>

The placeholders are `<your-gateway-url>` and `<your-api-access-token>` from Step 2, and `<tool-name>` from the `tools/list` response. The first call returns the tools the gateway exposes; the second invokes one. No browser, no interactive login.

## Step 4: Confirm attribution, then know how to cut it off

Open [Logs](https://app.mcpmanager.ai/settings/logs) and find your `tools/call`. It carries the same detail as an interactive call — the gateway, the server, the tool, the timing — attributed to the **CI bot** host and the user who generated the token. Token-driven automation is not an anonymous side channel; it's on the same audit trail as everyone else.

To revoke access, delete the token's connection from the host in [Apps & Agents](https://app.mcpmanager.ai/settings/hosts). The token stops working immediately — your break-glass control if a credential is ever exposed.

<Check>
  You created a host to represent an automation, issued it a gateway-scoped bearer token, called a tool over plain HTTP, saw the call attributed and logged, and learned how to revoke it instantly. That's a headless agent under the same governance as every interactive user.
</Check>

## Further reading

<CardGroup cols={2}>
  <Card title="API Tokens & Headless Agents" icon="key" href="/features/api-tokens-and-headless-agents">
    The full reference: token-based hosts, rotation, break-glass, and per-user identity for agents.
  </Card>

  <Card title="Trace a call in your logs" icon="magnifying-glass" href="/tutorials/trace-in-logs">
    Read the attributed log entry your token just produced.
  </Card>

  <Card title="Programmatic Access" icon="code" href="/enterprise/programmatic-access">
    Automating MCP Manager itself, beyond calling tools through a gateway.
  </Card>

  <Card title="Connection Experience" icon="plug-circle-check" href="/features/connection-experience">
    How the same authorize flow serves both headed and token-based hosts.
  </Card>
</CardGroup>