Connecting MCP Clients

Connect any MCP client that supports remote HTTP MCP plus OAuth 2.0 discovery. The same connection gives every client access to the same Structured Agent Knowledge graph — no per-client integration work.

Setup

Know your auth URL

You connect to the auth worker, not directly to a region server. The MCP endpoint is:

https://api.locusgraph.com/mcp

The same auth worker also serves OAuth discovery:

https://api.locusgraph.com/.well-known/oauth-protected-resource
https://api.locusgraph.com/.well-known/oauth-authorization-server
https://api.locusgraph.com/.well-known/openid-configuration

Configure remote MCP

Configure your client to use the remote /mcp endpoint above. Do not point the client at a local npx @locusgraph/mcp-server command unless you intentionally maintain a separate stdio wrapper.

MCP endpoint:        https://api.locusgraph.com/mcp
Protected resource:  https://api.locusgraph.com/.well-known/oauth-protected-resource
Authorization:       OAuth 2.0 authorization code flow

Complete OAuth

When the client connects, the auth worker returns OAuth metadata and the client completes the authorization code flow:

The client discovers metadata from /.well-known/oauth-protected-resource
It registers dynamically at /oauth/register, or uses a preconfigured static client
The user signs in at /oauth/authorize
The user selects a graph
The auth worker returns an access token bound to that graph

Verify the connection

Ask your client to:

initialize the MCP session
list tools
list resources
list prompts

You should see the four tools, the locusgraph://contexts resource, and the auto_capture prompt.

The auth worker accepts both dynamic OAuth clients and an env-managed static client. Static client credentials are configured with MCP_OAUTH_CLIENT_ID, MCP_OAUTH_CLIENT_SECRET, and MCP_OAUTH_REDIRECT_URIS.

The production auth base URL is https://api.locusgraph.com.

Client-Specific Guides

Use the dedicated Claude Code page for the full remote HTTP, OAuth, scope, and .mcp.json setup flow:

Claude Code

Set up LocusGraph in Claude Code with remote HTTP MCP and OAuth.

Static Client Helper

For ChatGPT or any deployment where you want a fixed OAuth client, generate credentials from the auth app:

cd apps/auth
./scripts/generate-mcp-client.sh chatgpt-locusgraph-prod

Set the printed values in your Worker secrets/config, then add the exact redirect URI your MCP client provides.

Required Auth Worker Configuration

Variable	Required	Purpose
`OAUTH_REDIRECT_URL`	Yes	Public base URL of the auth worker
`MCP_OAUTH_CLIENT_ID`	No	Static OAuth client ID for env-managed clients
`MCP_OAUTH_CLIENT_SECRET`	No	Static OAuth client secret
`MCP_OAUTH_REDIRECT_URIS`	No	Comma-separated allowed callback URIs
`MCP_OAUTH_SCOPES`	No	OAuth scopes; defaults to `profile memory.read memory.write`
`OPENAI_APPS_CHALLENGE`	No	OpenAI Apps verification challenge file
`LOCUSGRAPH_SERVER_URL`	No	Region server override for local development

Redirect URI Rules

The auth worker accepts redirect URIs that are:

https://...
loopback http://localhost... or http://127.0.0.1...
a valid custom native-app scheme such as myapp://callback

It rejects browser-executable schemes such as javascript:, data:, or file:.

The current auth worker is OAuth-based MCP. The older agent-secret examples are stale for this deployment path.

Troubleshooting

Problem	Fix
`401 Authentication required` from `/mcp`	Complete the OAuth flow first. Only `initialize` is unauthenticated.
`invalid_target` during OAuth	Use the auth worker's `/mcp` resource URL, not the region server URL.
Public client rejected	Public clients must use PKCE with `code_challenge_method=S256`.
MCP calls fail with missing graph access	Select a graph during `/oauth/authorize`; issued tokens are graph-bound.
Redirect URI rejected	Use HTTPS, loopback HTTP, or a valid native-app custom scheme.

Quickstart

Store and retrieve your first knowledge event with LocusGraph.

MCP Tools