# Configure the Locus Pro MCP server

Use Streamable HTTP at:

```text
https://api.paywithlocus.com/api/credits/mcp
```

Use the MCP runtime's native OAuth support. Do not add an Authorization header
or put `LOCUS_AGENT_CREDENTIAL` in the MCP configuration. Locus publishes the
protected-resource and authorization-server metadata, supports Authorization
Code with PKCE S256 and OAuth Device Authorization, and issues 15-minute access
tokens with rotating refresh tokens when the client requests `offline_access`.

When the Locus authorization screen opens, an agent-owned account chooses
**Continue with AgentID** and approves with the same AgentID used during signup.
A human-owned account sees the normal Locus sign-in screen and a direct link to
create an account. **Continue with AgentID** remains a secondary option for
agent-owned accounts.

## OpenClaw

Check `openclaw mcp --help` for the installed version, then add or update the
trusted server without changing unrelated entries. Current releases accept:

```bash
openclaw mcp set locus '{"url":"https://api.paywithlocus.com/api/credits/mcp","transport":"streamable-http","auth":"oauth"}'
openclaw mcp login locus
```

The login command prints the authorization URL. Complete AgentID approval and,
when the CLI requests it, provide the returned authorization code or final
callback URL. Run `openclaw mcp doctor` after login. Never paste an OAuth token
into the JSON configuration.

If this OpenClaw version lacks remote OAuth login, upgrade it. Do not fall back
to installing the `lcac_` setup credential as a static MCP header.

## Hermes Agent

Use Hermes' OAuth mode:

```bash
hermes mcp add --url https://api.paywithlocus.com/api/credits/mcp --auth oauth locus
hermes mcp login locus
```

Hermes performs dynamic client registration and PKCE, stores tokens beneath
its owner-only MCP token directory, and refreshes them automatically. Reload
MCP after login if the server is not immediately visible.

Current Hermes releases can finish remote login by accepting the complete
callback URL (or its `code` and `state` parameters) at the waiting prompt. Open
the printed authorization URL on any device, approve it, copy the callback URL
shown by Locus, and paste it back into that prompt. If an older Hermes build
rejects Client ID Metadata Documents during registration, retry its documented
DCR mode by setting `mcp_servers.locus.oauth.cimd` to `false`; do not configure
a static Locus bearer credential.

## Headless hosts

AgentID approval is an HTTP and JWS protocol; it does not require a GUI browser.
Keep the MCP login process and any loopback callback listener alive, then:

1. Fetch the authorization URL printed by the MCP client and follow redirects
   to the Locus consent URL. Preserve the OAuth client's PKCE state by leaving
   the login process running.
2. Read the opaque `request=lmo_req_...` value from that Locus URL.
3. Request the signed-out context without an Authorization header:

   ```http
   GET https://api.paywithlocus.com/api/credits/mcp/oauth/authorize/public-context?request=<lmo_req_...>
   ```

4. Read `data.agentIdAuthorizationUrl` from the JSON response.
5. Complete the cookie-preserving approval procedure in
   `https://paywithlocus.com/agent/auth.md`: GET the AgentID URL, approve its
   22-character request ID with the inbox key, then GET
   `/v0/authorize/continue?jti=...` using the same cookie jar.
6. Follow every redirect. AgentID returns to Locus, and Locus returns the
   authorization code to the exact callback URI registered by the MCP client.
   For a remote loopback URI, Locus displays a completion page instead of
   navigating to the wrong machine. Copy its complete callback URL into the
   client's documented manual-callback prompt. SSH port forwarding remains an
   optional alternative.

Do not send this task to the human merely because the host has no GUI. Human
involvement remains appropriate when AgentMail requires its one-time inbox
verification or when Stripe funding is ready.

## Device Authorization for headless clients

Clients that implement RFC 8628 can avoid loopback callbacks entirely. Read
`device_authorization_endpoint` from Locus authorization-server metadata, then
POST `client_id`, the exact MCP `resource`, and requested `scope` as form data.
Locus returns a high-entropy `device_code`, short `user_code`,
`verification_uri`, `verification_uri_complete`, expiry, and polling interval.

Show the human the verification link and code while polling the normal token
endpoint with grant type
`urn:ietf:params:oauth:grant-type:device_code`. Honor `authorization_pending`,
increase the interval after `slow_down`, and stop on `access_denied` or
`expired_token`. Only the client receives the device code and resulting tokens;
the browser approves the connection but never receives either token.

Device Authorization is additive. A client that does not implement it should
continue using Authorization Code + PKCE and the manual callback handoff above.

## Generic MCP clients

Configure the remote server URL and select OAuth. The conceptual configuration
is:

```json
{
  "name": "locus",
  "transport": "streamable-http",
  "url": "https://api.paywithlocus.com/api/credits/mcp",
  "auth": "oauth"
}
```

Field names vary by client. A compatible client must support remote MCP OAuth,
PKCE S256, and either dynamic client registration or Client ID Metadata
Documents. For unattended use it should request `offline_access`, persist the
refresh token securely, rotate it on refresh, and retry after refreshing a
401. The client—not the skill or a project `.env` file—owns these tokens.

## Compatibility credential

The agent signup response currently includes an `lcac_` credential so the
canonical skill can search the catalog, enable APIs, create a funding session,
and recover an account. The server temporarily continues accepting that value
on the MCP endpoint for compatibility. New installs must not use that backdoor:
it bypasses the OAuth token-family connection accounting and does not receive
normal refresh-token rotation.