Krosoft Wiki
Auto Light Dark
Auto Light Dark

MCP connection reference

Connection and OAuth contracts for MCP client developers and integrators.

The MCP server name is confluence. Initialization advertises it as serverInfo.name; OAuth protected-resource metadata uses the same resource_name. A client may display its configured connection name instead. Use confluence for that name; see connection naming and existing connections.

Connection contract

Use <base>/rest/native-mcp/1.0/mcp, where <base> is the Confluence base URL including its context path.

  • Transport: Streamable HTTP with JSON responses and negotiated per-request SSE. There is no local stdio server, standalone GET stream or Mcp-Session-Id.

  • Protocols: 2025-03-26, 2025-06-18 and 2025-11-25. Supports initialization, ping, tool discovery and calls.

  • OAuth: discover the app’s authorization server, obtain an MCP access token and send Authorization: Bearer <access-token>. An administrator must enable OAuth first.

  • PAT: send Authorization: Bearer <PAT> with a Confluence personal access token. No OAuth discovery, client registration or consent is needed. Store the token in private client credential storage.

MCP OAuth tokens work only for this MCP resource, not native Confluence REST. Tokens from Confluence’s separate OAuth provider are not MCP authorization. Native Basic or session authentication depends on the client and site configuration. All operations run as the authenticated caller, subject to native permissions and MCP policies.

See Client compatibility for connection support and Client guides for setup walkthroughs.

OAuth protocol and discovery

When OAuth is enabled, an unauthenticated MCP request receives 401 with a Bearer challenge containing resource_metadata. Follow that URL to protected-resource metadata, then discover the authorization and token endpoints from server metadata.

Purpose

URL

MCP resource

<base>/rest/native-mcp/1.0/mcp

Protected-resource metadata

<base>/rest/native-mcp/1.0/oauth/protected-resource

Issuer

<base>/rest/native-mcp/1.0/oauth

Server metadata

<issuer>/.well-known/oauth-authorization-server
Also available at <issuer>/.well-known/openid-configuration

Use the authorization code flow with PKCE S256. Scopes are mcp.read and mcp.write; read scope exposes only read tools. Redirect URIs must exactly match the client’s registered or metadata-listed URLs. Use absolute HTTPS URIs, or HTTP loopback URIs for desktop clients, without fragments or user information.

  • Metadata clients: a public client uses its HTTPS metadata URL as client_id. When client metadata documents are allowed, no manual registration or secret is needed. Confluence fetches the document directly, without a proxy or redirects; sites with proxy-only internet access need registered clients. DNS lookup is limited to three seconds; exhausted resolution capacity fails promptly instead of queuing.

  • Registered clients: public clients use PKCE without a secret. Confidential clients use PKCE plus client_secret_post or client_secret_basic, using one authentication method per request. There is no dynamic client registration.

Server metadata includes client_id_metadata_document_supported: true while metadata clients are allowed. Public clients, including metadata clients, must not send a secret. See OAuth administration for enabling OAuth, client registration and revocation.

OAuth request details

Authorize: <base>/plugins/servlet/native-mcp/oauth/authorize. Required parameters: response_type=code, client_id, redirect_uri, state, code_challenge and code_challenge_method=S256. Optional scope defaults to both scopes; optional resource must equal the MCP resource URL. Native Confluence login and explicit consent are required. The callback includes code, state and iss; codes are single use and valid for 60 seconds.

Exchange: POST to <issuer>/token with grant_type=authorization_code, code, redirect_uri, code_verifier and client identification/authentication. Responses contain access_token, refresh_token, expires_in (3600 seconds) and granted scope.

Refresh: use grant_type=refresh_token with the refresh token and client identification/authentication; scope may narrow access. Refresh rotates the token; reuse revokes the grant. Refresh tokens expire after 30 days.

Revoke: POST token and client identification/authentication to <issuer>/revoke. Revoking an access or refresh token revokes its grant.

Token and revocation POSTs require application/x-www-form-urlencoded bodies and a known Content-Length of at most 192 KiB (196,608 bytes). Larger forms receive 413, unknown-length or chunked forms 411, and unsupported media types 415. Do not put parameters in the query string.

Configure MCP behind a reverse proxy

Use the existing HTTPS Confluence proxy. Match Confluence’s base URL to the public hostname and context path, for example https://your-host/confluence.

  • Preserve Authorization, request bodies, response codes and authentication/rate-limit headers. Do not cache MCP responses or redirect API requests to a login page.

  • Disable response buffering for streaming and allow sufficient idle time. Use node affinity for uploads and continuation cursors on clustered sites.

  • Keep public OAuth issuer/resource URLs unchanged and normal browser login and consent available. Preserve the bounded form content length described above. Normal Confluence upload limits are separate.

Optional host-root OAuth discovery mappings

Cursor Desktop, Claude Code and Codex require host-root OAuth discovery mappings. Use internal rewrites, preserving the public issuer and resource URLs. Replace or omit /confluence to match the context path. PAT connections do not need these mappings.

Incoming path

Forward to

/.well-known/oauth-authorization-server/confluence/rest/native-mcp/1.0/oauth
/.well-known/oauth-authorization-server

/confluence/rest/native-mcp/1.0/oauth/.well-known/oauth-authorization-server

/.well-known/oauth-protected-resource/confluence/rest/native-mcp/1.0/mcp
/.well-known/oauth-protected-resource

/confluence/rest/native-mcp/1.0/oauth/protected-resource

Unqualified host-root paths must not replace discovery for another OAuth service on the same hostname. Use a dedicated hostname where needed. The app provides OAuth metadata; it does not provide OpenID Connect sign-in.

Deployment controls and diagnostics

Verify the connection

  1. Initialize the MCP connection and discover tools.

  2. Call confluence_get_current_user with {} and check executedAs in its successful result. Discovery alone does not verify the account. Verify intended content workflows separately.

For result decoding, errors and mutation retry rules, see Tool result handling.

The authenticated <base>/rest/native-mcp/1.0/mcp/info endpoint reports the executing user and effective space policy; it is a diagnostic endpoint, not the MCP connection URL. Empty policy lists mean no administrator filter, not the user’s accessible spaces. readOnly: false means write tools exist, not that every caller can write.

Deployment checks

The Confluence server must reach its configured base URL for search. Its JVM must trust that URL’s certificate, and any proxy must preserve caller authentication. If authentication fails, check the public URL and forwarded credentials; if progress is delayed, check buffering and idle timeouts.

Use Confluence and proxy controls for deployment-wide request size, timeouts and concurrency. MCP policies configure the app’s per-user rate and burst limit; streaming also has per-node and per-caller limits.