Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Connecting MCP Clients

Connect any MCP client that supports remote HTTP MCP plus OAuth 2.0 discovery.

Setup

1
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
2
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
3
Complete OAuth

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

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

Ask your client to:

  1. initialize the MCP session
  2. list tools
  3. list resources
  4. 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

VariableRequiredPurpose
OAUTH_REDIRECT_URLYesPublic base URL of the auth worker
MCP_OAUTH_CLIENT_IDNoStatic OAuth client ID for env-managed clients
MCP_OAUTH_CLIENT_SECRETNoStatic OAuth client secret
MCP_OAUTH_REDIRECT_URISNoComma-separated allowed callback URIs
MCP_OAUTH_SCOPESNoOAuth scopes; defaults to profile memory.read memory.write
OPENAI_APPS_CHALLENGENoOpenAI Apps verification challenge file
LOCUSGRAPH_SERVER_URLNoRegion 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

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

Next

Quickstart
Store and retrieve your first knowledge with LocusGraph.
MCP Tools
Full reference for all LocusGraph MCP tools.