MCP and OAuth

Start with the right address

https://api.kyroco.ai/mcp

Use Streamable HTTP as the transport. This is the service address for assistants and integrations. https://app.kyroco.ai is the human-facing application, not the MCP endpoint.

For a supported client, start with the dedicated Codex or Claude Code guide. This page is for understanding the connection or implementing another client. An agent can read the same steps as plain text in auth.md.

What happens during sign-in

1. The client discovers the protected resource and its authorization server.
2. It uses an existing client registration or the advertised dynamic registration endpoint.
3. It opens the browser with the requested scopes, redirect address and an S256 PKCE challenge.
4. You sign in. If the client receives the sign-in on a remote server rather than on your own computer, Korium asks you to allow that client the first time.
5. The client receives the one-time authorization code and exchanges it using the PKCE verifier.
6. The client stores its tokens securely and uses its refresh flow when needed.

Keep the resource identifier consistent with discovery. If the client sends a resource parameter for a different address, the server can reject it as invalid_target. Don’t hard-code authorization endpoints from another environment.

Choose what the connection can do

The protocol still uses the engram.* scope names. Do not rename them to korium.*. Request scopes explicitly rather than assuming a valid token includes every permission.

A typical read/write connection requests engram.read engram.write offline_access. A read-only connection requests engram.read offline_access. In Codex’s command-line login, the same list is comma-separated.

Read-only limits which product tools the client may call. Retrieval can still update internal use and activation records; read-only does not mean every storage counter remains unchanged.

If you are implementing a client

Use the discovery metadata rather than guessing endpoint names. Korium supports dynamic registration for compatible clients, authorization code with S256 PKCE and rotating refresh tokens. Store the registration and refresh state securely so the client can reconnect without registering on every run.

Declare only redirect addresses the client actually handles. Production web redirects need HTTPS; a native client can use supported loopback or app-scheme redirects. Validate the returned state and keep the authorization-server metadata associated with the credential.

Serialize refresh operations for a connection. Two processes racing with the same rotating refresh credential can turn a healthy connection into a replay or stale-token failure. Don’t print a token to debug that race.

Tool filtering is not authorization

A client may hide tools to reduce what the model sees. That is useful, but it does not remove permissions from the token. If the connection must not write, enforce that through the requested and granted scopes.

Korium applies tool access checks on the server and filters the tools it advertises to the connection. A client with no capture tool may have the wrong scope, rather than a broken installation.

Prove the connection works

1. List the available tools and confirm the expected Korium tool suffixes appear.
2. Search for a harmless known memory. An empty result on an empty workspace is valid.
3. For a write-enabled connection, capture a labeled test memory and check the returned thought_id.
4. Retrieve it from a fresh session connected to the same workspace.
5. Test reconnect and refresh without copying credentials between clients.

For code search, separately verify the repository identity and checkout SHA. Successful authentication does not create a code index.

Diagnose the failing stage

A browser callback that fails, a token refresh error and a refused tool call are different failures. Keep the exact message, client version, server address and time. Review logs for secrets before sharing them.

Do not diagnose every 401 as an elapsed token lifetime. Check discovery metadata, the granted scopes, refresh behavior, revocation and whether the credential belongs to the intended environment. The troubleshooting guide walks through those checks.