Locus product guide · Updated September 29, 2026

How to connect an MCP server to any AI agent

To connect Locus to any MCP client, add https://api.paywithlocus.com/api/credits/mcp as a remote Streamable HTTP server and leave the auth headers empty. The client discovers OAuth 2.1 with PKCE and opens Locus in your browser once. Agents that take prompts can install from SKILL.md instead. Headless services send a scoped bearer credential.

Setup, step by step

Step 1
Add the server URL
In your client, add a remote MCP server. Choose Streamable HTTP (sometimes labeled HTTP) if it asks for a transport.
```
https://api.paywithlocus.com/api/credits/mcp
```
Step 2
Leave authentication to the client
Do not add an Authorization header or API key. Choose OAuth if the client asks. Leave the client ID blank unless your client requires one.
Step 3
Approve Locus in your browser
The client opens Locus sign-in once. Sign in or create an account and approve the scopes mcp:read, mcp:execute, and offline_access. The client stores and refreshes the tokens.
Step 4
Make a free test call
Ask the agent a question that calls the free balance tool. A reply with your credit balance proves discovery, sign-in, and tool calls work.
```
What's my Locus balance?
```

What connection details does an MCP client need?

A client needs the URL, the transport, and support for OAuth discovery. Everything else comes from the server. These are the values the Locus Connect page shows for any other client.

What connection details does an MCP client need?
Setting	Value
Transport	Streamable HTTP
Server URL	https://api.paywithlocus.com/api/credits/mcp
Authentication	OAuth 2.1 discovery + Authorization Code / PKCE (S256)
Normal one-time grant	mcp:read mcp:execute offline_access
Discovery-only grant	mcp:read offline_access
Redirect URI	Exact HTTPS URI. Native clients may also use an RFC 8252 reverse-domain private-use URI or loopback HTTP, with only the port varying

How does remote MCP server OAuth work with Locus?

Locus follows the MCP authorization spec. A client that implements that spec needs only the server URL.

An unauthenticated request gets HTTP 401 with a WWW-Authenticate header that points to the protected resource metadata. That document names the authorization server at https://api.paywithlocus.com/api/credits/mcp/oauth. Its metadata lists the authorize, token, registration, device, and revocation endpoints.

Client registration: Client ID Metadata Documents or dynamic client registration. No client secret (public clients).
PKCE: S256 only.
Grants: authorization code, refresh token, and device code for hosts without a local browser.
Tokens are bound to the MCP server with the resource parameter. Add offline_access to get a refresh token.

How do I connect an agent that takes instructions instead of a URL?

Send it one sentence. Agent runtimes such as OpenClaw, Hermes, Muse, and Instinct set Locus up themselves from the installer file.

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

The agent picks the MCP or CLI adapter your host supports, installs the locus, locus-setup, and locus-workflows skills, and asks you to approve access in your browser.

How do I use the Locus CLI instead of MCP?

Install the CLI, then sign in. This suits terminal agents and scripts. The installer verifies the download checksum and adds the Locus skill to agent skill folders it finds.

Install: curl -fsSL https://paywithlocus.com/install/locus | sh

Sign in: locus auth login. Check it with locus auth status. The Connect page shows the same login with the production URL pinned: locus --base-url https://api.paywithlocus.com/api auth login.

Add --agent to any command for JSON output, no prompts, and no color. The installer puts the binary in ~/.local/bin by default, so add that folder to your PATH if the shell cannot find locus.

How does a headless service or enterprise agent connect?

Send a scoped agent connection credential as a bearer token. Use it when nothing can complete a browser sign-in.

Header: Authorization: Bearer $LOCUS_AGENT_CONNECTION

A workspace administrator creates the credential in API keys, then Service credentials, scoped to a bundle of catalog tools for that workflow. Its lcac_ value is shown once. Keep it in a secret manager, never in source control or a prompt. A tenant service key also works for trusted servers only.

Personal accounts do not issue long-lived keys. If your host cannot complete OAuth, connect Locus through an OAuth-capable MCP client or bridge.

Which guide covers my AI agent or MCP client?

Most hosts have a tested easiest method. Use the host guide when there is one. Use this page for anything else.

Frequently asked questions

Does Locus support stdio MCP clients?

Locus is a remote server only, over Streamable HTTP. A stdio-only client needs a bridge that speaks Streamable HTTP and OAuth. We have not tested a specific bridge.

Can I load fewer tools into my client?

Yes. Use https://api.paywithlocus.com/api/credits/mcp?surface=compact. It loads short discovery and execution tools and still reaches the same catalog through execute.

Has this generic path been tested?

The named hosts in the table were tested one by one. We have not tested every MCP client. If a client fails, check that it supports OAuth discovery and Streamable HTTP.

Does connecting cost anything?

No. The Free plan has no subscription, and the balance check is free. Paid tool calls use prepaid credits at the price shown before the call.

Implementation references

Use these first-party references for current request contracts and account requirements. Tool availability, prices, and negotiated terms can change.

Sources

Third-party details were checked on September 29, 2026. Vendors change pricing and features often, so confirm on their site before you decide.