Locus plugin

Pay-per-use APIs for coding agents. This plugin connects the Locus MCP server and teaches your agent how to use it well: cited web research, paid data and API lookups, and thousands of metered provider endpoints billed to one prepaid workspace credit balance.

One repo, many agents. Claude Code, Codex, and Grok can install the plugin directly today. Other clients can use the same repository's MCP configuration, three Agent Skills, or the one-URL bootstrap below.

What you get

• MCP server connection to https://api.paywithlocus.com/api/credits/mcp (streamable HTTP). Sign-in is OAuth with browser consent; no keys are stored in configuration.
• The locus skill: operating instructions for the agent covering tool routing, cost quotes, idempotent billing, error recovery, and spend safety.
• The locus-setup skill: onboarding when the user asks the agent to do it. Human sign-up through the OAuth page is the default. Agent-owned accounts via AgentID exist for headless runtimes, and only they get agent-driven capability selection and a user-requested Stripe funding handoff; human-owned accounts manage both in the dashboard.
• The locus-workflows skill: safe hosted Workflow authoring, fixtures, bounded pilots, immutable versions, and durable run recovery through the same authorized connection.

No account yet? Authenticate the server and create the account on the OAuth sign-in page that opens; that is the whole flow for a person with a browser. Tools are enabled and credits added in the dashboard at platform.paywithlocus.com.

Install

Claude Code CLI

/plugin marketplace add locus-technologies/locus-pro-plugin
/plugin install locus@locus

Then run /mcp, select locus, and authenticate.

Already added the server manually as locus-pro via claude mcp add? Remove it first (claude mcp remove locus-pro) so you don't carry two connections to the same server.

Claude Code app

In Code, open Customize → Plugins → Add plugin → Add marketplace → Add from a repository. Choose locus-technologies/locus-pro-plugin, select Sync, then Add Locus. Authenticate the plugin from Terminal:

claude mcp login plugin:locus:locus

Complete browser consent, then start a new Code session. The plugin loads all three skills and the Locus MCP connection together.

Claude Cowork and claude.ai

Open Customize → Connectors → Yours → Add connector → Add custom connector. Name it Locus, use https://api.paywithlocus.com/api/credits/mcp, then connect through browser OAuth. Under Customize → Skills → Yours → Add skill, upload all three:

• locus.zip
• locus-setup.zip
• locus-workflows.zip

ChatGPT.com

Enable Developer mode under Settings → Apps → Advanced settings, then open Plugins → Create app. Use the production MCP URL above and OAuth. If the current custom-skill picker rejects the production archives, keep the MCP app and use get_locus_guide for the same versioned operating guides.

Codex

codex plugin marketplace add locus-technologies/locus-pro-plugin
codex plugin add locus@locus
codex mcp login locus

Hermes

Send this prompt to Hermes:

Install Locus Pro by following https://paywithlocus.com/SKILL.md. Use production.

The bootstrap installs a supported adapter and all three released skill trees, then guides browser or device authentication. The official Hermes plugin listing is still pending; hermes plugins install locus is not live yet.

Cline

cline mcp install locus --transport http \
  https://api.paywithlocus.com/api/credits/mcp

Keep Remote (HTTP), choose OAuth, leave the client ID blank for dynamic registration, and complete sign-in in the browser. No clone, build, API key, or environment variable is required. Then install all three skills:

npx skills add locus-technologies/locus-pro-plugin

Select locus, locus-setup, and locus-workflows, then start a new session.

Cursor

Add the MCP server directly in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "locus": {
      "url": "https://api.paywithlocus.com/api/credits/mcp",
      "headers": { "X-Source-Name": "cursor-plugin" }
    }
  }
}

Cursor's OAuth flow completes in the browser on first use. Once the Locus listing clears Cursor Marketplace review, you will also be able to install it from Customize → Plugins (search "Locus") or with /add-plugin locus in chat. Until then, install the three skills separately with npx skills add locus-technologies/locus-pro-plugin and select all three.

Grok

grok plugin install locus-technologies/locus-pro-plugin --trust

Grok requires explicit trust to install plugins (they can run MCP servers and skills); review the repo, then pass --trust. Grok discovers the server's OAuth automatically and opens the browser flow on first use.

OpenClaw

Send this prompt to OpenClaw:

Install Locus Pro by following https://paywithlocus.com/SKILL.md. Use production.

The bootstrap installs a supported adapter and all three released skill trees. Current OpenClaw can unpack the marketplace bundle but does not import its MCP server, so do not use the marketplace route until that host behavior changes.

Muse and Instinct

Send either agent the same tested prompt:

Install Locus Pro by following https://paywithlocus.com/SKILL.md. Use production.

Skill only (77+ agents)

npx skills add locus-technologies/locus-pro-plugin

Discovers the Locus usage, setup, and Workflow skills and installs your selection into whichever agents you have. The skills include the connection instructions; add the MCP server in your client's settings to make the tools available.

Any Agent Plugins client

npx plugins add locus-technologies/locus-pro-plugin

Plain MCP (no plugin)

claude mcp add --transport http locus https://api.paywithlocus.com/api/credits/mcp
codex mcp add locus --url https://api.paywithlocus.com/api/credits/mcp

On file-capable clients, pair this with the Skill only install above. On an MCP-only host, call get_locus_guide after connecting.

One-URL bootstrap and remote guides

Ask a capable agent to read https://paywithlocus.com/SKILL.md and set up Locus. The bootstrap probes the actual host, preserves a healthy existing connection, selects a supported adapter, and reports any browser consent, restart, or runtime limitation still outstanding.

An MCP-only host does not need persistent files. After connecting, it can call get_locus_guide to retrieve the same versioned skill and reference content published in this repository. The public guide manifest is served from the Locus API; customer-owned Workflow source and invocation guides remain private account artifacts and never enter that public bundle.

Hosted Workflow tools are advertised only when the backend capability is live and the current connection can execute. A Workflow run is a constrained child of that existing connection, not a second registered agent. The first runtime supports approved TypeScript and every live catalog binding Locus has reviewed, including native Tools, maintained Recipes, and explicitly verified external buyer-rail listings. Tenant-imported and unverified external bindings require an exceptional platform approval; a server deny override can halt any binding. Connection scope, enablement, contract, availability, and run budgets still apply. The runtime also provides bounded concurrency, fixtures, pilots, durable inspection, cancellation, and resume; arbitrary npm dependencies, external connector credentials, scheduling, and publication are not implied.

Data handling

The plugin-managed MCP configs send one static request header, X-Source-Name (for example cursor-plugin). It identifies the configuration format a host selected and may be used solely for anonymous adoption telemetry; multi-format hosts can prefer a different bundled definition than their own overlay — OpenClaw's bundle loader, for example, honors the root .mcp.json and therefore reports grok-plugin. The header is cosmetic: plain MCP clients that cannot configure static headers still work without it.

The repository contains no credential values, and its MCP configurations store none. Tool calls send the arguments the agent provides to https://api.paywithlocus.com and are billed to the authenticated workspace. If the user explicitly chooses the optional agent-owned setup path, the setup skill also calls https://api.agentmail.to to create and verify an inbox and register a public signing key, https://api.auth.agentid.com to submit a signed approval, and https://auth.agentid.com to continue that authorization transaction. AgentMail receives only the user-approved email address and inbox name, the user-provided one-time code, and the public key; AgentID receives the inbox identity and a one-time signed assertion. The private signing key is generated locally and is never sent. Funding calls https://api.paywithlocus.com and returns a server-provided Stripe Checkout URL that the user opens in a browser; neither the plugin nor the agent handles card details.

Authentication and credentials

Human-owned MCP connections use OAuth 2.1 with dynamic client registration: your client discovers it from the URL, opens a browser sign-in, and a consent screen in the Locus dashboard scopes the connection. Access and refresh tokens stay in the client's native OAuth store, never in this repo's files.

The optional agent-owned setup path may create an AGENTMAIL_API_KEY, a locally generated P-256 signing key, and an lcac_ value stored as LOCUS_AGENT_CREDENTIAL. Keep them only in the runtime's approved secret store; never put them in MCP configuration, chat, project files, source control, logs, or command arguments. LOCUS_SECRET_KEY is referenced only as a credential class to protect; the skills never read or set it, and neither lcr_ nor lcac_ values belong in MCP configuration.

Costs and safety

Paid provider calls are live and billed to your workspace credit balance; catalog discovery, quotes, and balance checks are free. The skill instructs agents to pass idempotency keys so a retry reusing its key never double-charges, to quote significant calls with estimate_cost first, and to confirm with you before unusually large spends. Spend limits and approvals are configured per workspace in the dashboard.

Repository layout

Development and releases

Changes merge into stage. Before promotion, a maintainer explicitly chooses one semantic version for every host manifest and writes its changelog entry; CI checks that coordinated version but never updates it. A validated stage to main promotion creates the immutable GitHub release, checksummed plugin and skill archives, the Agent Skills discovery payload, and the matching MCP Registry version. Public directories that require vendor review (OpenAI and Cursor) are submitted through their review portals after that release.

See AGENTS.md for the branch policy, required checks, release prerequisites, and isolated local testing instructions for production and the stage MCP environment across Claude Code, Codex, Cursor, Grok, OpenClaw, Agent Plugins, Agent Skills, and ChatGPT.

Links

• Docs: https://docs.paywithlocus.com
• Dashboard: https://platform.paywithlocus.com
• MCP reference: https://paywithlocus.com/agent/mcp.md

License

MIT