MCP Client Configuration

This page explains how to connect MCP clients to Kuroco using OAuth 2.0.

Setup takes three steps:

1. Check the Supported clients tables for your client. Each client name links directly to its setup instructions.
2. Complete the Kuroco-side setup. In most cases, enabling CIMD on a default authorization server is all you need.
3. Follow your client's setup instructions to connect to Kuroco.

We also support authenticating via a request header (X-RCMS-API-ACCESS-TOKEN) — see MCP Client Configuration with Authentication Header — but OAuth is the recommended approach.

Before configuring an OAuth connection, check the Issuer URL shown in the Kuroco admin UI. The Issuer URL identifies the authorization server. If the MCP client has an Issuer URL or OAuth Issuer field, enter this URL. See Check the Issuer URL for where to find it and an example.

Supported clients

Client names link to the setup instructions for each client.

Chat-based clients

Client	OAuth support	CIMD	Manual client registration	Header authentication
Jan	❌	❌	❌	✅
Claude (Web / Desktop / Mobile)	✅	✅	✅	❌
ChatGPT (Developer mode)	✅	✅	✅	❌
Slackbot	✅	❌	✅	❌

Coding assistants

Client	OAuth support	CIMD	Manual client registration	Header authentication
Claude Code	✅	✅	✅	✅
Codex CLI	❌	❌	❌	✅
Cursor	✅	❌	✅	✅
GitHub Copilot Chat (VS Code)	✅	✅	✅	✅
GitHub Copilot coding agent	❌	❌	❌	✅

Custom implementations

Client	OAuth support	CIMD	Manual client registration	Header authentication
Python / TypeScript / other custom MCP clients	✅	Depends on client implementation	✅	✅

Notes:

• CIMD is a draft IETF spec (draft-ietf-oauth-client-id-metadata-document). Support across clients is recent and evolving — re-verify against each vendor's current docs before relying on it in production.
• "Manual client registration" means the client lets a user configure a pre-registered client_id/client_secret. Clients without this option can only use OAuth against authorization servers that support CIMD or RFC 7591 DCR.
• "Header authentication" means the client can authenticate by setting an access token in the request header (X-RCMS-API-ACCESS-TOKEN). For setup instructions, see MCP Client Configuration with Authentication Header.

Kuroco OAuth Client registration support

An MCP client needs a client_id (and, for confidential clients, a client_secret) before it can start an OAuth Authorization Code flow against Kuroco. Kuroco supports two ways to obtain one:

1. CIMD (Client ID Metadata Document) — the client's client_id is itself an HTTPS URL that resolves to a small JSON document describing the client (redirect_uris, client_name, etc.). Kuroco fetches and validates that document on first use and no admin action is required per client. This is what Claude, Claude Code, ChatGPT, and GitHub Copilot Chat use. CIMD is now the default and recommended client registration method for MCP — the MCP authorization specification marks the older Dynamic Client Registration (DCR) mechanism as deprecated in its latest draft.
2. Manual client registration — an admin pre-registers the client in the Kuroco admin UI and hands the generated client_id (and client_secret, if applicable) to whoever configures the MCP client. Use this for clients that don't support CIMD, such as Cursor, or whenever you'd simply rather manage clients explicitly.

Kuroco does not implement OAuth Dynamic Client Registration (RFC 7591 — the POST /register flow), in line with that deprecation. Clients that only support RFC 7591 DCR and have no manual-configuration option (e.g. Codex CLI) currently cannot complete OAuth against Kuroco.

Kuroco-side setup

OAuth login is triggered for APIs whose security is set to Dynamic Token or Cookie. APIs whose security is Static Token or Privileged Static Token use token authentication via the X-RCMS-API-ACCESS-TOKEN header instead of OAuth (see MCP Client Configuration with Authentication Header). For public endpoints (security = none), the procedure for adding the MCP server to a client is the same, but no OAuth login step occurs since there is nothing to authenticate.

caution

Public endpoints are not recommended for production use. Since no authentication is required, anyone who knows the URL can access the API and request origin cannot be tracked. If you must use a public endpoint, restrict it to read-only operations and only expose data that is truly safe to make public. Never expose write endpoints without authentication.

OAuth in Kuroco is built around an authorization server which issues tokens, and, optionally, one or more registered clients under it. First check the Issuer URL, then choose one of the two setup methods.

Check the Issuer URL

For an OAuth connection, the Issuer URL shown in the Kuroco admin UI identifies the authorization server. It uses the following format:

https://your_site_key.g.kuroco-mng.app/direct/login/oauth_idp/{idpid}

This example shows the URL format. Do not construct the URL manually; use the exact value shown on the OAuth Authorization Server editor (/management/external/memberregist_sso_oauth_idp_edit/). For Admin MCP, you can also find it on the Admin MCP settings screen (/management/rcms_api/admin_mcp_info/).

If the MCP client has an Issuer URL or OAuth Issuer field, enter this URL. If the client has no Issuer URL field and supports automatic OAuth discovery, registering the MCP server URL causes the authorization server information to be discovered. You can still verify that the intended authorization server was discovered by comparing it with the Issuer URL shown in the Kuroco admin UI.

If the client asks for an MCP server URL or Server URL, enter the URL of the MCP server you want to use, not the Issuer URL. See the MCP Server Reference for MCP server URL formats.

If the client asks for a Client ID or Client Secret, enter the values issued when the OAuth Authorization Server client was saved only when using manual client registration. Do not enter them when using CIMD.

Option 1: Client ID Metadata Document (CIMD)

Kuroco automatically creates two default authorization servers the first time they're needed: Admin MCP (default) (the admin management MCP endpoint) and Kuroco MCP API (default) (content APIs exposed via /rcms-api/{api_id}/mcp). In most cases you just need to edit one of these defaults and enable CIMD if not already enabled. Creating a new custom authorization server is only needed for more advanced setups (e.g. a separate authorization server per content API with different scopes/grant types).

Use the default authorization server

Go to External system integration > Identity federation > OAuth Authorization Server in the admin UI.

Open the default authorization server matching the endpoint you want to expose (Admin MCP (default) or Kuroco MCP API (default)) and enable Client ID Metadata Documents (URL client IDs) if not already enabled.

Create a new custom authorization server

From the same list screen, click Add and configure:

Field	Description
Name	Free-text label for this authorization server.
Target Domain	What this authorization server protects — API (a content API exposed via /rcms-api/{api_id}/mcp), Management, or AdminMCP (the admin management MCP endpoint, /direct/rcms_api/admin_mcp/...). Immutable after creation. Only one enabled authorization server is allowed for Management/AdminMCP site-wide.
Client ID Metadata Documents (URL client IDs)	This is the CIMD on/off switch. Enable it to allow clients to authenticate with a client_id that is a metadata URL (e.g. Claude Code, ChatGPT).
Supported Grant Types	authorization_code, refresh_token, client_credentials — whichever your clients need.
Allowed Scopes	Scope catalog for this domain. For AdminMCP, individual scopes aren't exposed as checkboxes here — instead, each client's access is set via a single permission-level selector (Read-only / Read & write / Full access, see below), which assigns the scopes automatically on save (Read-only = mcp:tools.read, Read & write = mcp:tools.read + mcp:tools.write, Full access = mcp:admin; the tool-listing scope mcp:tools.list is granted automatically at every level).
Access Token TTL / Refresh Token TTL / Authorization Code TTL	Token lifetimes in seconds (defaults: 3600 / 2592000 / 60).

Target Domain must be chosen at creation time and cannot be changed afterward.

Once created, an API-domain authorization server can be assigned to a specific content API from the API structure list (/management/rcms_api/api_list/): open that API's MCP settings tab and pick it from the OAuth Authorization Server dropdown.

Once CIMD is enabled on the relevant authorization server, clients that support it need nothing further — proceed straight to that client's CIMD section below.

Option 2: Manual client registration

Use this for clients whose Manual client registration section below tells you to configure a client_id/secret directly — for example Cursor.

Go to External system integration > Identity federation > OAuth Authorization Server > Clients, scoped under the relevant authorization server.

Configure:

Field	Description
Client Name	Free-text label, e.g. "Cursor".
Token Endpoint Auth Method	none for a public client using PKCE (recommended for desktop apps like Cursor), or client_secret_basic / client_secret_post for a confidential client that securely stores a client secret.
Redirect URIs	One URI per line — the exact callback URL that the MCP client will redirect to after consent. This is fixed by the MCP client itself; check its documentation or settings for the correct value. Required when authorization_code is a selected grant type.
Supported Grant Types	Typically authorization_code + refresh_token. client_credentials requires a non-none auth method and a bound service member.
Allowed Scopes	Pick from the intersection of the target domain's scope catalog and the parent authorization server's Allowed Scopes. For an AdminMCP authorization server, this is instead a single permission-level selector (Read-only / Read & write / Full access) rather than individual scope checkboxes.
Enabled	Enable the client.

On save, Kuroco generates the Client ID automatically. If Token Endpoint Auth Method isn't none, a Client Secret is also generated and shown once — copy it immediately, as it cannot be displayed again afterward. Use "Regenerate secret" on the edit screen if it's lost.

Hand the generated Client ID (and Client Secret, if any) plus the token/authorization endpoints from the authorization server's metadata URL to whoever is configuring the MCP client.

Authorization server metadata URL

The OAuth Authorization Server editor (/management/external/memberregist_sso_oauth_idp_edit/) shows the authorization server's Metadata URL. If an MCP client asks for an "Authorization URL" or "Token URL," enter the authorization_endpoint and token_endpoint values from the JSON document at the Metadata URL. The document also contains the issuer and the supported grant types and scopes.

Chat-based clients

Jan

Jan can connect to Kuroco using header authentication. Its MCP integration supports a server URL plus static headers/environment variables — use the setup described in MCP Client Configuration with Authentication Header. Note that the OAuth authorization-code flow, CIMD, and manual client registration are not supported.

Claude (Web / Desktop / Mobile)

CIMD

Enable Client ID Metadata Documents (URL client IDs) on the relevant Kuroco authorization server, then:

1. Open Settings > Connectors.
2. Click Add custom connector.
3. Enter your remote MCP URL, e.g. https://your_site_key.g.kuroco.app/rcms-api/{api_id}/mcp.
4. Click Connect — a browser window opens for OAuth consent against your Kuroco authorization server. No further configuration is needed.

Manual client registration

If you would like to use manual client registration, register a client in Kuroco (see Register a client manually) with a redirect URI matching Claude's connector callback, then:

1. Open Settings > Connectors.
2. Click Add custom connector.
3. Enter your remote MCP URL.
4. Expand Advanced settings and enter the client_id/client_secret generated by Kuroco.
5. Click Connect to complete the OAuth consent flow.

For the steps to register a Kuroco connector using OAuth authentication, see How to Register an MCP Connector in Claude.ai.

Official references:

• Building custom connectors: authentication
• Getting started with custom connectors using remote MCP

ChatGPT Apps (Developer mode)

CIMD

Enable Client ID Metadata Documents (URL client IDs) on the relevant Kuroco authorization server, then:

1. Enable Developer mode for your workspace/user role.
2. Go to Apps > Create.
3. Enter your MCP endpoint — the connection completes without further configuration.

Manual client registration

If you would like to use manual client registration, register a client in Kuroco (see Register a client manually), then:

1. Enable Developer mode for your workspace/user role.
2. Go to Apps > Create.
3. Enter your MCP endpoint.
4. Supply the manually-registered client_id/client_secret when prompted.

Official reference:

• Developer mode, and MCP apps in ChatGPT (beta)

Slackbot

Slackbot does not support CIMD. Manual client registration is the only way to connect it to Kuroco with OAuth.

CIMD

Not supported by Slackbot.

Manual client registration

Register a client in Kuroco (see Register a client manually) with:

• Redirect URIs: https://oauth2.slack.com/external/auth/callback
• Token Endpoint Auth Method: client_secret_post

Then, in Slack:

1. Create a Slack app from scratch at api.slack.com/apps.
2. In the app settings, open the MCP Servers section and click Add MCP Server.
3. Enter a Name and the URL of your Kuroco MCP endpoint, and set Auth to Manual OAuth.
4. Enter the Client ID and Client Secret generated by Kuroco. Get the Authorization URL and Token request URL from the authorization server's metadata URL. Enable Use PKCE (Proof Key for Code Exchange) and leave the remaining fields empty.

Once added, the MCP server's tools are available to Slackbot in any Slack conversation.

Coding assistants

Claude Code

CIMD

Enable Client ID Metadata Documents (URL client IDs) on the relevant Kuroco authorization server. Claude Code auto-discovers CIMD support and uses its own hosted client metadata document (https://claude.ai/oauth/claude-code-client-metadata) — no further configuration is needed on the Kuroco side.

claude mcp add --transport http kuroco https://your_site_key.g.kuroco.app/rcms-api/{api_id}/mcp
claude mcp login kuroco

Manual client registration

If you would like to use manual client registration, register a client in Kuroco (see Register a client manually), then pass the credentials directly:

claude mcp add --transport http kuroco https://your_site_key.g.kuroco.app/rcms-api/{api_id}/mcp \
  --client-id "your-client-id" --client-secret "your-client-secret"

Official reference:

• Claude Code MCP

Codex CLI

Codex CLI only performs RFC 7591 Dynamic Client Registration and has no manual client-credential option, and does not support CIMD. Since Kuroco does not implement a DCR /register endpoint, Codex CLI cannot currently authenticate to Kuroco via OAuth. Use the authentication header setup from MCP Client Configuration with Authentication Header instead.

Cursor

Cursor performs RFC 7591 DCR by default, which Kuroco does not implement, and does not support CIMD. Manual client registration is the only way to connect it to Kuroco with OAuth.

CIMD

Not yet supported by Cursor.

Manual client registration

Register a client in Kuroco (see Register a client manually) with redirect_uris set to Cursor's fixed callback URLs:

• Web: https://www.cursor.com/agents/mcp/oauth/callback
• Desktop: cursor://anysphere.cursor-mcp/oauth/callback

Then configure mcp.json directly:

{
  "mcpServers": {
    "kuroco": {
      "url": "https://your_site_key.g.kuroco.app/rcms-api/{api_id}/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-oauth-client-secret",
        "scopes": ["your", "selected", "scopes"]
      }
    }
  }
}

Official reference:

• Cursor MCP docs

GitHub Copilot Chat (VS Code)

VS Code's MCP client tries CIMD first, then DCR (unsupported by Kuroco), then prompts for manual client_id/client_secret if neither is available.

CIMD

Enable Client ID Metadata Documents (URL client IDs) on the relevant Kuroco authorization server. Configure just the server URL:

{
  "servers": {
    "kuroco": {
      "type": "http",
      "url": "https://your_site_key.g.kuroco.app/rcms-api/{api_id}/mcp"
    }
  }
}

No oauth block is needed — negotiation is triggered by a 401 + WWW-Authenticate response from Kuroco.

Manual client registration

If you would like to use manual client registration, register a client in Kuroco (see Register a client manually). VS Code prompts for the client_id/client_secret interactively when it adds the server; manage saved credentials afterward via Accounts menu > Manage Trusted MCP Servers.

Official references:

• Using MCP with GitHub Copilot
• VS Code MCP configuration reference

GitHub Copilot coding agent

The coding agent does not support OAuth for remote MCP servers — GitHub's docs state it explicitly, so neither CIMD nor manual client registration apply. Use a repository secret prefixed COPILOT_MCP_ and a static bearer header instead:

{
  "mcpServers": {
    "kuroco": {
      "type": "http",
      "url": "https://your_site_key.g.kuroco.app/rcms-api/{api_id}/mcp",
      "headers": {
        "Authorization": "Bearer $COPILOT_MCP_KUROCO_TOKEN"
      }
    }
  }
}

This requires the target API's security to be set to Static Token or Privileged Static Token (see MCP Client Configuration with Authentication Header) rather than OAuth.

Official reference:

• Extending Copilot coding agent with MCP

Custom implementations

Python / TypeScript / others

Use the official MCP SDK's OAuth client support (most SDKs implement the authorization-code + PKCE flow and can be pointed at an arbitrary client_id).

CIMD

If your client supports CIMD, host a small JSON document at an HTTPS URL and use that URL as your client_id. Enable Client ID Metadata Documents (URL client IDs) on the relevant Kuroco authorization server.

Manual client registration

If you would like to use manual client registration, register a client in Kuroco (see Register a client manually) and configure your client with the resulting client_id/client_secret, plus the authorization server's authorization/token endpoints from its metadata URL.

Kuroco does not implement RFC 7591 DCR, so a custom client relying on POST /register will not work against Kuroco.

Related documents

• Model Context Protocol (MCP) Integration with Kuroco
• How to Register an MCP Connector in Claude.ai
• How to restrict API access with Static Access Token
• API security