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-18and2025-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 |
|
|
Protected-resource metadata |
|
|
Issuer |
|
|
Server metadata |
|
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_postorclient_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.
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.
Deployment controls and diagnostics
Verify the connection
-
Initialize the MCP connection and discover tools.
-
Call
confluence_get_current_userwith{}and checkexecutedAsin 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.
-
Security and permissions: native access checks, MCP audience, mode and space policy.
-
Compatibility and limitations: request, streaming, transfer and cluster limits.
-
Troubleshooting: connection and operation failures.