Connect with OAuth

An MCP client signs in with your own Solvimon login instead of an API key in a configuration file. The client registers itself, you approve it on a consent screen in Desk, and it receives a token scoped to the platforms you picked.

Why this matters

Connecting a client with an API key means pasting a long-lived credential into a configuration file on your machine. That key is as powerful as the account behind it, it does not expire, and nothing records which tool is using it.

OAuth replaces that. The client never sees a key. It gets a token that belongs to you, limited to the platforms you approved and the access it asked for, and you can see what you authorised. Setting it up is entering a URL and logging in, with no registration on Solvimon’s side.

How it works

Solvimon’s identity host is an OAuth 2.0 authorization server. Clients discover it, register themselves, and run the authorization code flow with PKCE.

Solvimon registers public clients only: a desktop application cannot keep a secret, so there is no client secret anywhere in this flow. PKCE is what proves that the client redeeming the code is the one that started the flow.

Discovery

Two documents sit at the root of the identity host:

curl https://identity.solvimon.com/.well-known/oauth-authorization-server

token_endpoint_auth_methods_supported is ["none"], grant_types_supported is ["authorization_code", "refresh_token"], and response_types_supported is ["code"].

Registration

A client that has never spoken to Solvimon registers itself with POST /v1/oauth2/register. The call needs no credentials, because a client that has never spoken to us has nothing to authenticate with:

curl -X POST https://identity.solvimon.com/v1/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Claude Code (my-laptop)",
    "redirect_uris": ["http://127.0.0.1:51703/callback"]
  }'

{
  "client_id": "...",
  "client_name": "Claude Code (my-laptop)",
  "redirect_uris": ["http://127.0.0.1:51703/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none"
}

Metadata Solvimon does not understand is ignored rather than refused, as the specification requires. A rejected redirect URI answers invalid_redirect_uri, and other bad metadata answers invalid_client_metadata.

Scopes

A client asks for one or both on the authorize call. Scopes Solvimon does not recognise are dropped rather than refused, and a request that ends up naming none is narrowed to solvimon:read. The consent screen shows what was granted, read back from the stored request, not what the client asked for.

The consent screen

The authorize call sends the browser to Desk, where you sign in with your normal Solvimon account. The screen names the application, shows the access it is asking for, and lists the platforms you are a member of. You pick which of them the client may reach, then approve or deny.

A single-membership user has their platform preselected. Approving mints a one-time code that is valid for 60 seconds and redeems exactly once.

The token exchange

The client posts the code and its PKCE verifier to POST /v1/oauth2/token. The response is a bearer token bound to the platforms you selected and the scope that was granted. A refresh token is issued alongside it, so the client does not have to send you back to the consent screen on every expiry.

Via Desk

There is nothing to set up in Desk in advance. The consent screen appears on its own when a client starts the flow, and signing in is your normal Desk login.

Edge cases

• A refused authorization looks the same whichever way it failed. An expired request, an unknown one, a browser that did not start the flow and the wrong user all answer one 403. The reason is logged on Solvimon’s side rather than shown, because distinguishing them in the browser tells an attacker which guess was closest. An authorization request lives five minutes, so expiry is the usual cause.
• Recognition is not verification. The client name on the consent screen is chosen by whoever registered the client. Desk shows a logo for clients it recognises by name, and nothing for one it does not, because a badge next to an unknown name would read as a guarantee. Read the name and the platforms carefully before approving.
• An API key still works. The X-API-KEY connection described in Claude integration is unchanged. OAuth is the alternative, not a replacement, and is the better choice for a client on a personal machine.
• Impersonation is restricted. X-ORIGINAL-USER is honoured only for an API key of type PROXY, and only for the accounts that key may reach.

See also: Claude integration for connecting a client, Agent context for the guidance an agent reads from your catalog, and Developing for Solvimon.