Sign InGet Started

Registering Custom MCP Clients

Register a third-party MCP client application so it can authenticate against Hamster's MCP server with its own OAuth client ID.

Overview

Most AI coding tools — Claude Code, Cursor, Windsurf, Codex — register with Hamster's MCP server automatically and only need the server URL (see Getting Started).

Custom or third-party MCP client applications that can't self-register need a pre-registered OAuth client instead. If you have the connections.manage permission, you can register one from Workspace Settings → MCP integrations, and Hamster issues a public PKCE client ID (no client secret) that your app uses to authenticate.

Register a New Client

  1. Open Workspace Settings → MCP integrations.
  2. Click Register a new client application.
  3. Provide:
    • Application name — a human-readable name for your MCP tool (e.g. "My Research Agent").
    • Exact HTTPS redirect URIs — one or more HTTPS URLs where your client receives auth callbacks (e.g. https://my-agent.example.com/auth/callback).
  4. Click Register.
  5. Hamster generates a public PKCE client ID. Use it in your MCP tool's configuration — there is no client secret; PKCE handles token exchange securely.

Manage Registered Clients

Registered clients appear in the Registered Applications list, where you can:

  • View client details — the client ID, redirect URIs, and creation date.
  • Edit registration — add or remove redirect URIs. The application name is fixed at registration.
  • Revoke registration — block new authorizations for the client. Already-issued tokens stay valid until they expire or are revoked through the authorization provider.

How Custom Clients Authenticate

Once registered, your client follows the same OAuth 2.1 PKCE flow as any MCP tool:

  1. It discovers Hamster's authorization server via /.well-known/oauth-protected-resource.
  2. It opens your browser to sign in with your Hamster credentials.
  3. You approve the connection.
  4. Hamster returns a session token to the client; subsequent calls use it until it expires or the authorization is revoked.

Every call runs as the signed-in user and respects that user's role — a Reviewer's client can read but not create Briefs; an Admin's can write. Registering a client does not grant any admin override at the MCP layer.

Related