# Authentication for agents

workerfuse MCP supports two ways to sign in: OAuth 2.1 and API keys.

## OAuth (recommended for MCP clients)

Add the MCP server URL to the client. No key is needed:

```sh
claude mcp add --transport http workerfuse https://workerfuse.com/mcp
```

The first request without credentials gets HTTP 401 with:

```
WWW-Authenticate: Bearer resource_metadata="https://workerfuse.com/.well-known/oauth-protected-resource/mcp", scope="spend:read guard:write"
```

The client then follows standard MCP authorization:

- Protected resource metadata (RFC 9728): https://workerfuse.com/.well-known/oauth-protected-resource/mcp
- Authorization server metadata (RFC 8414): https://workerfuse.com/.well-known/oauth-authorization-server/api/auth (also served at https://workerfuse.com/.well-known/oauth-authorization-server)
- Dynamic client registration (RFC 7591): no initial access token is needed.
- Authorization code with PKCE `S256` only. Tokens are bound to the resource `https://workerfuse.com/mcp` (RFC 8707).
- Access tokens last one hour. Refresh tokens rotate, and a used refresh token cannot be used again.

The user signs in or signs up in the browser and approves the client. The user can untick scopes on the approval page, for example to give an agent read-only access.

## Scopes

| Scope | Allows |
|---|---|
| `spend:read` | `list_accounts`, `get_spend` and `list_events` |
| `guard:write` | `pause_script`, `resume_script`, `set_limits` and `connect_cloudflare_account` |
| `offline_access` | A refresh token, so the client stays connected |

Ask for `spend:read` only if the agent does not need to change anything. A call without the needed scope gets HTTP 403 with `error="insufficient_scope"` and the missing scope, so the client can ask the user again.

## API keys

Sign up at [workerfuse.com/signup](https://workerfuse.com/signup). workerfuse shows a `wf_` API key one time, with no manual approval. workerfuse stores only a hash of the key.

An API key has full access: every scope above, for every Cloudflare account that the login connects. Use a key when a client cannot do OAuth, and for the self-hosted guard's `CONTROL_KEY`.

```sh
curl https://workerfuse.com/mcp \
  -H "Authorization: Bearer $WORKERFUSE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_spend","arguments":{"accountId":"<32-hex Cloudflare account ID>"}}}'
```

Guard report: `POST https://workerfuse.com/api/report` with the same header. See [openapi.json](https://workerfuse.com/openapi.json).

## What needs credentials

| Request | Credentials | Plan |
|---|---|---|
| MCP `server/discover` | No | No |
| MCP `initialize`, `tools/list` | OAuth token or API key | No |
| MCP `tools/call` with `connect_cloudflare_account` | OAuth token with `guard:write`, or API key | No. It starts the trial. |
| Other MCP `tools/call` | OAuth token with the tool's scope, or API key | Trial or active subscription |
| `POST /api/report` | API key | No. A lapsed plan gets `plan: "lapsed"`. |

A lapsed plan gets HTTP 403 on tool calls.

## Revoke access

- OAuth clients: open [Settings](https://workerfuse.com/settings), find the client under **Connected agents**, and click **Revoke**. The client stops working at once.
- API key: click **Rotate key** in Settings. The new key is shown one time. The old key and old email resume links stop working. Update the guard's `CONTROL_KEY` secret and every client that used the key.

## Browser sign-in

The dashboard uses an email and password session at [workerfuse.com/login](https://workerfuse.com/login). A browser session cannot call MCP tools.

## Support

support@workerfuse.com
