--- name: locus-pro description: "Connect an AI agent to Locus Pro through either native MCP OAuth or the separately installed Okibi-generated Locus API CLI; select paid API capabilities and create a Stripe funding handoff. Use when an OpenClaw, Hermes, hosted, or custom agent needs Locus access. Preserve the user's requested integration: MCP and CLI are separate paths, and neither is the default." --- # Locus Pro Create and configure this agent's own prepaid Locus Pro account through the integration the user requested. Complete only that path's identity, capability, credential-storage, and connection steps. Involve the human only when an identity provider requests approval, AgentMail needs its one-time verification code, or the account is ready for funding. ## Choose the requested integration Locus offers two separate integration paths. Neither path is the default, and their order below conveys no preference: - **Install or connect the MCP server:** go directly to [the MCP installation guide](https://paywithlocus.com/agent/mcp.md). Do not probe for Okibi, install or invoke the generated `locus` CLI, run a `locus auth` command, or continue through the CLI section in this file. - **Install or use the generated CLI:** go directly to [CLI path: Okibi-generated Locus CLI](#cli-path-okibi-generated-locus-cli). Do not configure the MCP server as part of that path. Honor the user's explicit choice even when the other integration is available or already installed. A request mentioning “MCP,” “MCP server,” “Hermes MCP,” or an MCP OAuth connection selects the MCP path; it does not authorize a CLI installation. A request mentioning the Locus CLI or Okibi selects the CLI path. If the user has not selected either integration, ask which one they want before installing, authenticating, or probing either path. Do not infer a choice from the runtime, headless environment, manifest availability, or account owner. Production endpoints are shown below. When this file came from a stage or beta Locus hostname, use the environment-specific URLs already written into it and do not mix environments. ## Safety rules - Never invent a registration token. Generate it with a cryptographic RNG. - Never paste a Locus, Okibi, AgentMail, or AgentID secret or capability into chat, a project file, source control, a skill file, logs, or a command argument. - Send Locus credentials only to `https://api.paywithlocus.com`. - Treat a returned `lcac_` value as a scoped native setup and execution credential. Its endpoint allowlist is authoritative. Never put it in the MCP server configuration; the MCP connection must use OAuth. - Send the human only the Stripe `checkoutUrl`. Never request card data in chat. - Do not claim success until the selected CLI or MCP connection is working, chosen capabilities are enabled, and the funding status reports `ready`. Read [credential and runtime guidance](https://paywithlocus.com/agent/credentials.md) before persisting any secret. Read the [MCP configurations](https://paywithlocus.com/agent/mcp.md) when installing the connection. ## Native MCP account setup Follow this account setup only for the MCP path. Look for `LOCUS_AGENT_CREDENTIAL` in the runtime's approved secret store or environment without printing its value. If it exists, call: ```http GET https://api.paywithlocus.com/api/credits/agent/account Authorization: Bearer $LOCUS_AGENT_CREDENTIAL ``` If the request succeeds, continue to the MCP path. If the credential is missing, revoked, or belongs to another environment, continue with the matching account owner flow below. Do not switch to or install the CLI as a fallback. ### Choose the MCP account owner flow Use the path that matches the account owner. These are MCP OAuth and account signup choices; Okibi and the generated CLI are not prerequisites: 1. **Agent-owned account with an existing AgentID signing identity.** Continue to agent-native signup below. 2. **Human-owned account.** Give the human the authorization URL printed by the MCP client. They can sign in or create an account on that page. Do not pretend to control their email or ask them for a password. Continue to the MCP path; Locus preserves the pending connection through signup and verification. 3. **Agent-owned account without an inbox or AgentID identity.** Follow `https://agent.email/skill.md` to create an AgentMail inbox. Its one-time OTP is deliberate human friction. Then create a scoped P-256 signing key using the browserless contract below. Do not run `npx @agentmail/agentid-cli init` as an agent signup step. That command initializes a relying-party application; Locus is already the relying party. Read `https://paywithlocus.com/agent/auth.md` before creating an AgentID key or approving a signup. It contains the complete browserless contract; do not search for a separate procedure. ## CLI path: Okibi-generated Locus CLI Follow this section only when the user explicitly selected the generated CLI or Okibi path. Do not enter it while installing or repairing an MCP connection. First make an unauthenticated availability probe: ```http GET https://api.paywithlocus.com/.well-known/okibi-identity ``` Continue only when it returns `200` with an Okibi Identity manifest. A `404`, `feature_disabled`, or any other unavailable response means the CLI integration is unavailable. Report that result and stop this path. Do not switch to MCP or native Locus OAuth unless the user asks to use that separate integration. Install the official signed release, then read its bundled skill and command help before authenticating: ```bash curl -fsSL https://okibi.ai/i/locus/locus | sh export PATH="${LOCUS_BIN_DIR:-${HOME}/.local/bin}:${PATH}" locus --version locus auth login ``` The repo-backed production CLI targets `https://api.paywithlocus.com/api` by default. `locus auth login` uses Okibi Identity when the manifest is available and completes the protected Locus credential bootstrap; `locus auth native` is the explicit native fallback. The CLI sends short-lived, scoped Okibi capabilities only to Locus's bootstrap resource; never extract, print, persist, or copy one into an MCP configuration. Treat a successful protected command as the release-health check. A dashboard badge or a `200` manifest proves that the partner deployment is available, but does not by itself prove that the installed binary is covered by an Identity-eligible signed release. If the CLI reports `release is not Identity-eligible`, `Okibi Identity access is no longer active`, a release digest/signature mismatch, or no official signed installer, stop using that release and report the failure. Do not switch to MCP unless the user asks to use that separate integration, and do not downgrade a failed Okibi login by reusing its capability as a native bearer token. The protected release-health check is `GET https://api.paywithlocus.com/api/credits/okibi/cli-credential`. Use the generated command for that operation. It requires `mcp:read` and `mcp:execute` from Okibi and returns status only, never a native credential. A success proves the installed signed release, live Okibi grant, durable account binding, and current Locus membership are all usable together. On first approval, a verified Okibi identity directly provisions its own zero-credit Locus Pro workspace and returns `provisioned` when no eligible native account matches its verified email; it does not redirect through Locus sign-in or AgentID signup. Locus registers that account to the normalized verified email and keys ownership to the Okibi issuer and pairwise subject. Later requests recheck the durable subject binding, active account, and requested scopes. If the verified email matches an active Locus Cognito account with an eligible workspace, the short-lived Locus decision page asks whether to link it or create a separate Okibi-owned account. The email match is discovery only, never ownership proof. Choosing the existing account requires a matching Locus sign-in before the link is created. Choosing the separate account provisions it to the verified email without Locus login and lets the Okibi flow continue headlessly. An explicitly requested existing workspace uses the same proof-of-control boundary. A signed-in human confirms in the dashboard; an existing AgentID-owned headless account may read the short-lived token from the URL fragment and submit it without printing it: ```http POST https://api.paywithlocus.com/api/credits/okibi/link/confirm Authorization: Bearer $LOCUS_AGENT_CREDENTIAL Content-Type: application/json {"token":""} ``` Never put that token in a query string, log, shell argument, chat, or file. The confirmation pins Okibi only after the native Locus session or AgentID-owned connection proves control of the selected existing account. Declining that link never grants access to it; it creates a distinct Okibi-owned account instead. The normal `locus auth login` workflow performs the protected status check, generates the registration token locally, applies its least-privilege default tool allowlist (or the repeated `--tool` values supplied by the caller), exchanges the Okibi capability, and stores the returned native credential without printing it. If a runtime must drive the generated operation directly, generate exactly 24 random bytes as unpadded base64url, keep the token in its approved secret store, and call: ```http POST https://api.paywithlocus.com/api/credits/okibi/cli-credential Authorization: Content-Type: application/json { "registrationToken": "<32 base64url characters supplied over stdin>", "tools": {"enable": [""]} } ``` Use the generated CLI's stdin/JSON-input mode so the registration token is not a command argument. Select only the capabilities needed by this installation; Locus enables those catalog slugs and binds the returned 24-hour `lcac_` credential to the Okibi identity, CLI installation, workspace, and exact endpoint allowlist. Replaying the same registration token recovers and renews the credential; a fresh verified replay may replace its allowlist. A different token cannot take over the installation. When using the direct operation, capture `connection.credential` without printing it. Store it in the approved secret manager and inject it into the generated CLI process as `LOCUS_SECRET_KEY`; never put it in a positional argument. Clear any owner-only temporary response file immediately after the secret store confirms capture. The handoff is now complete: Okibi proves identity and bootstraps the scoped native Locus credential; ordinary generated API commands use that native credential. Okibi capabilities do not call Apollo or other paid providers directly. Run one selected read or paid API command and verify its real response and Locus billing metadata; a generic `{status:200,success:true}` envelope is not execution evidence. The native credential expires after 24 hours and current Locus membership is rechecked on every use, so replay the bootstrap with the same registration token before expiry. If no official Identity-eligible release or install link is available, report that the selected CLI path is unavailable. Do not switch to MCP without the user's direction. Never downgrade a rejected Okibi capability into a different bearer credential. ### Start agent-native signup for MCP Generate exactly 24 random bytes encoded as unpadded base64url. For example, when Python is available: ```bash LOCUS_REGISTRATION_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(24))')" ``` Keep that value in memory and send: ```http POST https://api.paywithlocus.com/api/credits/agent/register Content-Type: application/json { "name": "", "registrationToken": "$LOCUS_REGISTRATION_TOKEN", "agentEmail": "" } ``` A `202` response means only a short-lived pending registration exists. No tenant, credential, credits, or free account has been created yet. Fetch the returned `registration.authorizationUrl` while retaining its HTTP cookie. Extract the 22-character AgentID request ID, sign the exact approval payload described in `https://paywithlocus.com/agent/auth.md`, and submit it to AgentID. After the approval returns `204`, fetch `https://auth.agentid.com/v0/authorize/continue?jti=` with the same cookie and follow every redirect. Do not remove or alter the final `code`, `state`, or `iss` callback parameters. The private key must remain in the keystore; AgentID receives only a one-time signature. After approval, replay the exact same registration request with the same name and token. The successful response contains `account.connection.credential`. Store it immediately as `LOCUS_AGENT_CREDENTIAL` for the catalog and funding calls below, then clear the temporary registration token and any response file containing the credential. This compatibility credential is not the MCP credential. If registration says too many pending signups exist, finish an existing signup or wait for its 30-minute expiry. Do not rotate tokens to evade the limit. ## MCP path: Native OAuth Follow this section only when the user explicitly selected MCP. Do not probe, install, invoke, or authenticate through the generated Locus CLI while setting up or repairing MCP. Configure a Streamable HTTP server named `locus`: - URL: `https://api.paywithlocus.com/api/credits/mcp?surface=compact` - Authentication: the MCP client's native OAuth mode - Static headers: none Use the exact OpenClaw, Hermes, or generic configuration in `https://paywithlocus.com/agent/mcp.md`. Reload the MCP client and confirm that it discovers Locus OAuth, opens the authorization URL, and reaches the Locus authorization screen. For an agent-owned account, choose **AgentID** from the normal provider row and approve with the same AgentID identity used for signup. There is no separate MCP-specific AgentID button. For a human-owned account, send the printed authorization URL to the human; the page uses the normal Locus sign-in screen and includes a direct account-creation link. Locus returns short-lived access and rotating refresh tokens to the MCP client. Let the runtime keep them in its native OAuth store; do not copy them into an environment file. On a headless host, keep the MCP login process and any loopback listener alive. For a human-owned account, send the printed authorization URL to the human. After approval, Locus does not navigate to localhost. It shows one **Copy response to agent** action; the human copies those response parameters and the agent pastes them into the waiting MCP login prompt. For an agent-owned account, resolve the Locus request handle and complete the cookie-preserving AgentID procedure over HTTP. Full steps are in `https://paywithlocus.com/agent/mcp.md`. If the MCP client supports OAuth Device Authorization, prefer that mode on a remote host: it prints a six-character user code and verification link while the client polls for completion. The browser never receives the access or refresh token. Current Hermes MCP releases do not implement this flow and must use their authorization-code paste fallback. After authentication, use the five-tool compact MCP loop: 1. Use `search` with a plain-language intent to shortlist enabled APIs and recipes. 2. Use `describe` for only the selected slug before supplying arguments. 3. Use `estimate` for dynamic, expensive, or sensitive work. An execution-scoped estimate can return a binding `approval_token`; use its expiry to abandon an unused plan. 4. Use `execute` with the selected slug, validated arguments, a stable idempotency key, and the approval token when required. A dedicated pinned endpoint tool may be used only when no approval token is required. 5. If the call returns a receipt, a paginated or deferred result, or an uncertain final response with a known call ID, use `get_result` instead of repeating the paid call. Read `locus://balance` to inspect remaining credits. Existing connections may continue to call the legacy meta-tool names during migration, but new connections should use the five names above. Discovery does not enable a tool. A read-only or incomplete estimate is not an executable approval; only the returned `approval_token` is. Keep the capability allowlist and funding state separate from this invocation workflow. ## 5. Select capabilities Search by the outcome the agent needs, not by a guessed provider name: ```http POST https://api.paywithlocus.com/api/credits/agent/catalog/search Authorization: Bearer $LOCUS_AGENT_CREDENTIAL Content-Type: application/json {"query":"web research and source extraction","limit":10} ``` Review the returned descriptions and exact slugs. Enable only the capabilities needed for the agent's current responsibilities: ```http PUT https://api.paywithlocus.com/api/credits/agent/catalog Authorization: Bearer $LOCUS_AGENT_CREDENTIAL Content-Type: application/json {"slug":"","enabled":true} ``` Repeat for each selected capability. Do not enable the whole catalog. For GTM enrichment, enable the `gtm-enrichment` capability pack instead of manually enabling its provider endpoints. Then follow [the waterfall recipe](https://paywithlocus.com/agent/gtm-enrichment.md). ## 6. Ask the human to fund the configured account Read the current funding constraints first: ```http GET https://api.paywithlocus.com/api/credits/agent/funding/config Authorization: Bearer $LOCUS_AGENT_CREDENTIAL ``` Choose an amount within those constraints. Generate one stable idempotency key and reuse it only for retries of this same funding link: ```http POST https://api.paywithlocus.com/api/credits/agent/funding-sessions Authorization: Bearer $LOCUS_AGENT_CREDENTIAL Idempotency-Key: Content-Type: application/json {"usd":"10.00"} ``` Send the human the returned `humanHandoff.message` or `checkoutUrl`. Explain that this loads prepaid usage credits; the payer does not become the account owner and the payment method is not saved for autonomous future charges. Poll the returned `statusUrl` with the Locus credential at the suggested interval. Continue only when `state` is `ready`. If it expires or fails, create a new funding session with a new idempotency key. ## 7. Verify completion Confirm all of the following: - the account endpoint reports a positive balance and `onboardingState: ready`; - the Okibi-generated CLI can run Locus discovery commands, or the native MCP server is loaded and exposes the five compact tools; an execution-scoped session can additionally expose the enabled `router_web_search`, `web_research`, and `travel_flights` capability tools plus explicitly pinned tools. Verify MCP discovery with `search` and `describe` before invoking a selected capability with `execute`; - only the intended capabilities are enabled; - OAuth tokens are in the MCP runtime's native token store, and the compatibility setup credential is in an approved secret location; neither appears in the workspace or version control. For later credential rotation, generate a new 24-byte base64url token and call `POST /credits/agent/credential/rotate` with the current Locus credential. Move the replacement into the secret store atomically; the old credential stops working immediately.