Connect an agent

Connect your agent once to give it search, research, enrichment, and other paid tools from your Locus catalog. Locus handles provider access and billing; you choose the tools and spending limits.

Your runtime	Connection
A coding or desktop client you use interactively	OAuth
A hosted agent or background service	Enterprise service credential
An agent with its own account	Agent-native onboarding

Building with a model SDK? Go to Framework integrations. For direct API calls, use the Node SDK. See MCP for the tool reference and compact mode.

Connect an MCP client

The hosted MCP server uses Streamable HTTP:

MCP server URL

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

Interactive OAuth (recommended)

In your workspace, open Integrate → MCP clients. Add the MCP URL to your client and approve the connection in your browser. Locus Pro self-serve accounts use Connections. Choose the manual configuration below or the Locus plugin. You only need one connection.

Open Customize → Connectors → Yours → Add connector → Add custom connector. Name it Locus, enter the MCP server URL above, choose Connect, and complete browser sign-in.Then open Customize → Skills → Yours → Add skill → Upload skill and upload all three archives:

This supplies the remote connector and complete skill tree to Claude surfaces that expose these account settings. Claude Code uses its plugin path below.

Enable Developer mode under Settings → Apps → Advanced settings, then open Plugins → Create app. Enter the MCP server URL above, choose OAuth, and finish Locus sign-in. Start a Work task, open Plugins, and select Locus Pro before asking it to use a tool.This custom-app path provides the MCP tools. ChatGPT’s current Skills picker may leave valid production archives ineligible. The MCP app still works; use get_locus_guide for the same versioned operating guides when the upload is unavailable.

claude mcp add --transport http locus-pro \
  https://api.paywithlocus.com/api/credits/mcp

Run /mcp, select locus-pro, and choose Authenticate.

codex mcp add locus-pro --url https://api.paywithlocus.com/api/credits/mcp
codex mcp login locus-pro --scopes mcp:read,mcp:execute,offline_access

This direct configuration provides MCP tools only. Install the Codex plugin below to add all three skills with the connection.

Add this to ~/.cursor/mcp.json, enable the server, and follow the OAuth prompt:

~/.cursor/mcp.json

{
  "mcpServers": {
    "locus-pro": {
      "url": "https://api.paywithlocus.com/api/credits/mcp"
    }
  }
}

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

Choose Remote (HTTP) and OAuth, leave the client ID blank, and complete browser sign-in. Then install all three skills and start a new Cline session:

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

Select locus, locus-setup, and locus-workflows when prompted.

Install the Locus plugin

The Locus plugin bundles the OAuth connection with three skills: Locus for Tools and Recipes, Locus setup for onboarding, and Locus Workflows for building and running saved processes. Your client stores and refreshes the OAuth tokens.

Claude Code CLI
Claude Code app
Codex CLI / app
Grok

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

Run /mcp, select locus, and choose Authenticate.

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 locus, locus-setup, and locus-workflows with the MCP connection.If the login command says plugin:locus:locus is missing and claude mcp get locus reports a legacy Local config, remove the project entry, restart Code, and retry:

claude mcp remove locus -s local

codex plugin marketplace add locus-technologies/locus-pro-plugin
codex plugin add locus@locus
codex mcp login locus --scopes mcp:read,mcp:execute,offline_access

Start a new CLI or desktop session after installation. The plugin loads all three Locus skills with the MCP connection.

Review the plugin repository, then install:

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

Grok opens browser sign-in when you first use the connection.

Use one OAuth entry per client. If you install the plugin after adding the server manually, remove the duplicate manual entry. For a service credential, use the manual configuration below. Other Agent Plugins clients can install the same bundle:

Install the plugin

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

Update through your client’s plugin manager, then start a fresh session. See the release notes; public marketplace listings may update separately from GitHub.

One-link setup

For OpenClaw, Hermes, Muse, and Instinct, send this prompt in a new agent session:

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

The installer chooses a supported MCP or CLI adapter, installs locus, locus-setup, and locus-workflows, starts authentication, and checks a free readiness operation. Complete any browser approval or restart it requests.

Hermes does not currently have a public plugin listing. Current OpenClaw does not import the MCP entry from its marketplace bundle. Use the one-link route for both clients today.

Give your coding agent the Locus skills

Send your agent paywithlocus.com/SKILL.md, or install the skills when you are not using the plugin:

Install the skills

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

Select locus, locus-setup, and locus-workflows when prompted. A skills-only install still needs an authenticated MCP connection. Clients without local skill support can retrieve the same guides through MCP with get_locus_guide.

Enterprise service credentials

What an agent connection is

An Agent Connection gives one runtime access to a chosen balance and set of tools. You can set an expiry, a maximum charge per call, and a spending limit per run. Create it from API Keys → Service credentials or from your backend. Locus returns an lcac_… credential and ready-to-use MCP configuration.

Keep your lcr_… tenant secret key on your server. Give the agent a scoped lcac_… credential. Store credentials in a secret manager, never in prompts or source control.

Create a connection

Your server key needs both credentials:manage and credits:move to create or rotate a connection. Dashboard users must be an owner or admin and complete recent MFA or passkey verification.

Enable the tools

Enable the required endpoints in Agent tools. A connection can use only enabled workspace tools.

Create the credential

Create an Agent Connection

curl --fail-with-body -X POST "https://api.paywithlocus.com/api/credits/agent-connections" \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research-agent-prod",
    "mode": "platform",
    "tools": { "enable": ["tavily/search", "firecrawl/scrape"] },
    "maxCreditsPerCall": "250",
    "expiresInSeconds": 2592000
  }'

Save it securely

Store the returned credential immediately. It is shown only on creation and rotation.

Connection settings

Setting	What you choose
Account	`platform` for your pooled balance, or `end_user` with one `externalUserId`
Tools	Exact `provider/endpoint` slugs the agent may call
Per-call limit	The largest charge one call may incur, in credits
Per-run limit	A shared credit budget for calls with the same loop ID
Expiry	How long the connection remains valid

End-user connections can also carry their own pricing overrides. See the API reference for the full creation contract.

Omitting tools allows all workspace-enabled endpoints. An empty tools.enable list permits none. Account and tool scope are fixed at creation; create a replacement to change them.

Enterprise service-credential configuration

Set LOCUS_AGENT_CONNECTION to the saved lcac_… credential.

Codex
Claude Code
Cursor

Add to ~/.codex/config.toml:

~/.codex/config.toml

[mcp_servers.locus_pro]
url = "https://api.paywithlocus.com/api/credits/mcp"
bearer_token_env_var = "LOCUS_AGENT_CONNECTION"

: "${LOCUS_AGENT_CONNECTION:?Set LOCUS_AGENT_CONNECTION first}"
claude mcp add --transport http locus-pro \
  https://api.paywithlocus.com/api/credits/mcp \
  --header "Authorization: Bearer $LOCUS_AGENT_CONNECTION"

Run /mcp to connect. Remove an existing locus-pro entry before replacing it.

Add to .cursor/mcp.json and keep this file out of source control:

.cursor/mcp.json

{
  "mcpServers": {
    "locus-pro": {
      "url": "https://api.paywithlocus.com/api/credits/mcp",
      "headers": {
        "Authorization": "Bearer lcac_...your credential..."
      }
    }
  }
}

Hosted model APIs have their own authorization fields. Use the examples in Framework integrations.

Connection scope and budgets

To enforce a run budget, set maxCreditsPerLoop at creation. Give every paid call in that run the same ID:

Client	Where to pass it
Node SDK	`{ loopId: "run_42" }` in call options
REST	`X-Locus-Agent-Loop-Id: run_42`
MCP `execute`	`loop_id: "run_42"`
Dedicated MCP tool	`_locus: { "loop_id": "run_42" }`

Concurrent calls share the same budget. Start a new ID only for a new run.

Use the MCP tools

Ask your agent to find the tool it needs, check the price, and use the result:

Send to your agent

Find recent company news and funding information for this prospect.
Cite the sources and show what the research cost.

MCP exposes discovery and execution tools without loading the entire catalog. See all MCP tools for the names and compact-mode equivalents. When using a quote, pass its unchanged approval_token, arguments, and idempotency_key to execute. Dedicated endpoint tools cannot consume an approval token.

Idempotency and replay

Reuse one idempotency_key when retrying a paid call. Locus returns the stored outcome without charging again. Use a new key for an intentional repeat, such as refreshing a search.

Turn structured results into final answers

Store the paid result before asking the model to summarize it. If answer generation fails, reuse that result instead of repeating the purchase. The SDK provides parseMcpToolResult to check tool errors, prepareMcpResultForSynthesis to build bounded context, and selectSynthesisAnswer for a fallback answer. The Locus skill covers the full runtime flow.

Rotate or revoke a connection

Manage connections in API Keys → Service credentials, or use the SDK:

Rotate or revoke

const rotated = await locus.agentConnections.rotate(connectionId);
// Save rotated.credential; the old credential stops working immediately.

await locus.agentConnections.revoke(connectionId);

Rotation preserves scope. Revocation is immediate and permanent; a server key needs only credentials:manage to revoke a connection.

Troubleshoot a connection

Problem	Check
`401`	Complete OAuth sign-in, or check that the service credential is set, active, and unexpired
Missing tools or `403`	Enable the endpoint in your workspace and include it in the connection’s scope
`402`	Top up the account bound to the connection
Call or run limit exceeded	Use a cheaper tool or create a connection with a suitable budget
`AGENT_LOOP_ID_REQUIRED`	Pass the same loop ID on every call in the run
Client cannot initialize	Use the exact MCP URL and Streamable HTTP transport

Share the connection ID and error code with support. Never share the full credential.

Agent-owned headless OAuth

An agent-owned account signs in through AgentID. Keep the MCP login process alive while completing authorization so it retains its callback and PKCE state. Follow Agent-native onboarding and the AgentID authentication reference for the HTTP flow.

Headless device authorization (RFC 8628)

Clients without a redirect listener can register for the device-code grant. They display a verification link, wait for approval, and exchange the device code for tokens. The API reference documents registration, polling intervals, and token renewal.

Next steps

Framework integrations: connect your model SDK or agent framework.
SDK reference: make direct calls and manage connections.
Locus CLI: work from a terminal.

Getting started

Build with Locus Pro

Connect agents

Funding & billing

Developer tools

Catalog directory

Testing

Connect an MCP client

Interactive OAuth (recommended)

Install the Locus plugin

One-link setup

Give your coding agent the Locus skills

Enterprise service credentials

What an agent connection is

Create a connection

Enterprise service-credential configuration

Connection scope and budgets

Use the MCP tools

Idempotency and replay

Turn structured results into final answers

Rotate or revoke a connection

Troubleshoot a connection

Agent-owned headless OAuth

Headless device authorization (RFC 8628)

Next steps

​Connect an MCP client

​Interactive OAuth (recommended)

​Install the Locus plugin

​One-link setup

​Give your coding agent the Locus skills

​Enterprise service credentials

​What an agent connection is

​Create a connection

​Enterprise service-credential configuration

​Connection scope and budgets

​Use the MCP tools

​Idempotency and replay

​Turn structured results into final answers

​Rotate or revoke a connection

​Troubleshoot a connection

​Agent-owned headless OAuth

​Headless device authorization (RFC 8628)

​Next steps

Connect an MCP client

Interactive OAuth (recommended)

Install the Locus plugin

One-link setup

Give your coding agent the Locus skills

Enterprise service credentials

What an agent connection is

Create a connection

Enterprise service-credential configuration

Connection scope and budgets

Use the MCP tools

Idempotency and replay

Turn structured results into final answers

Rotate or revoke a connection

Troubleshoot a connection

Agent-owned headless OAuth

Headless device authorization (RFC 8628)

Next steps