Custom integrations

If you're building your own AI agent — or wiring KlyHub into a tool that does not have first-party MCP support yet — this guide walks you through the OAuth 2.1 flow and the raw MCP endpoint.

What you need

• Client type — confidential (server-side) or public (browser/desktop with PKCE).
• OAuth discovery URL — https://accounts.klyhub.com/.well-known/oauth-authorization-server.
• MCP endpoint — https://mcp.klyhub.com/v1/<tenant-slug>.

KlyHub is an OAuth 2.1 authorization server with PKCE mandatory (per RFC 9700, no exceptions). Dynamic Client Registration (DCR) is supported but rate-limited.

Step 1 — Register your client

Two options:

Option A — Manual registration (recommended for first integrations). In your KlyHub workspace, open Settings → MCP clients → Register custom client. KlyHub asks for:

• Client name (shown on the consent screen).
• redirect_uris (one or more — exact string match is enforced; no wildcards, no path segments rewritten).
• Token endpoint auth method (client_secret_basic, client_secret_post, or none for public clients with PKCE).

KlyHub returns client_id (and client_secret for confidential clients).

Option B — Dynamic Client Registration. POST an RFC 7591 registration request to:

https://accounts.klyhub.com/oauth/register

DCR is rate-limited (currently 5 registrations per IP per hour) — for production deployments prefer Option A.

Step 2 — Authorization Code Flow with PKCE

Standard OAuth 2.1 flow:

1. Generate a code_verifier (43–128 chars, URL-safe) and the matching code_challenge (SHA256(verifier), base64url-encoded).
2. Redirect the user to:

   https://accounts.klyhub.com/oauth/authorize
     ?response_type=code
     &client_id=<your_id>
     &redirect_uri=<exact_match>
     &code_challenge=<challenge>
     &code_challenge_method=S256
     &scope=mcp.read mcp.write
     &state=<random>

3. After the user approves, KlyHub redirects to your redirect_uri with code + state.
4. Exchange the code for tokens:

   POST https://accounts.klyhub.com/oauth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code
   &code=<code>
   &redirect_uri=<exact_match>
   &code_verifier=<verifier>
   &client_id=<your_id>

KlyHub returns:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "mcp.read mcp.write"
}

The access token carries aud=mcp.klyhub.com and iss=accounts.klyhub.com claims — the MCP server validates both before accepting the call. Your client does not need to inspect the token; just include it.

Step 3 — Call the MCP endpoint

KlyHub's MCP server speaks the MCP protocol at:

POST https://mcp.klyhub.com/v1/<tenant-slug>
Authorization: Bearer <access_token>
Content-Type: application/json

The protocol pin is 2025-06-18, with version negotiation supporting 2025-11-25 clients automatically.

Use the official @modelcontextprotocol/sdk (1.24+) for your language of choice rather than hand-rolling the JSON-RPC envelopes.

Step 4 — Refresh tokens

When access_token expires, exchange the refresh token:

POST https://accounts.klyhub.com/oauth/token

grant_type=refresh_token
&refresh_token=<refresh_token>
&client_id=<your_id>

Refresh tokens rotate — every refresh issues a new refresh token and invalidates the old one. Store the latest one.

Notes

• Idempotency — every write tool accepts an idempotency_key (UUID); KlyHub caches the result for 24h so retries are safe.
• Quota errors — when a tenant hits its plan quota, write tools return QUOTA_EXCEEDED and the MCP adapter surfaces it as isError=true. Read tools keep working.
• Read-only state — if billing fails or the tenant is scheduled for deletion, all write tools return errors with explanatory text. Read tools still work.

For ready-made client examples, see Connect Claude Desktop, Cursor, or ChatGPT.