MCP

Connect MCP clients — Claude Desktop, Cursor, or any Model Context Protocol client — to your Corkboard workspace over a Streamable HTTP transport secured with OAuth 2.1.

Server Endpoint

Corkboard exposes an MCP server at a single endpoint using the Streamable HTTP transport:

https://your-instance.example/mcp

The server accepts JSON-RPC messages over HTTP POST and supports Server-Sent Events for streaming responses. It is built on laravel/mcp and follows the MCP authorization specification (2025-11-25).

OAuth 2.1 Discovery

MCP clients authenticate with Corkboard using OAuth 2.1. The discovery flow follows a two-step chain starting from Corkboard's own metadata document:

1. Fetch the Protected Resource Metadata. Your MCP client requests Corkboard's OAuth metadata:

   GET https://your-instance.example/.well-known/oauth-protected-resource/mcp

   The response identifies Corkboard as an OAuth 2.1 resource server and points to its authorization server:

   {
     "resource":             "https://your-instance.example/mcp",
     "authorization_servers": ["https://YOUR_TENANT.auth0.com"],
     "scopes_supported":     ["mcp:use"],
     "bearer_methods_supported": ["header"]
   }

2. Follow the authorization server's OpenID Connect discovery. With the authorization server URL from step 1, your client fetches Auth0's well-known configuration:

   GET https://YOUR_TENANT.auth0.com/.well-known/openid-configuration

   This document provides the authorization_endpoint, token_endpoint, and supported grant types that your client uses for the remainder of the OAuth flow.
3. Obtain an access token. Your client initiates the OAuth 2.1 authorization code flow (with PKCE) against Auth0. When requesting the token, include the MCP resource identifier as the audience parameter — see Token Audience below.
4. Send the token as a Bearer header. Include the access token in every MCP request:

   Authorization: Bearer <your-access-token>

Scopes

The MCP server requires a single OAuth scope:

mcp:use

This scope is enforced by the mcp.scope middleware. Requests that pass authentication but lack the mcp:use scope receive a 403 response with a clear error so your client can request the missing scope.

Token Audience

MCP authentication uses a dedicated token audience, distinct from the HTTP REST API, per RFC 8707.

In plain English: an audience is the identifier that tells Auth0 which resource the token is meant for. Think of it as the "intended recipient" stamped into the token. Corkboard has two separate audiences:

• AUTH0_MCP_AUDIENCE — tokens minted with this audience are accepted by the MCP server at /mcp.
• The HTTP API audience (separate config value) — tokens minted for the REST API.

A token minted for the API will not work for MCP, and vice versa. When configuring your MCP client, ensure the token request includes the correct audience value. The audience string is configured server-side via AUTH0_MCP_AUDIENCE — if you do not know your workspace's audience, check your Auth0 dashboard or ask your workspace administrator.

Client Configuration

Replace https://your-instance.example with your Corkboard workspace URL in every snippet below.

Claude Desktop

Add the following entry to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "corkboard": {
      "type": "streamableHttp",
      "url": "https://your-instance.example/mcp",
      "auth": {
        "type": "oauth2",
        "authorizationUrl": "https://YOUR_TENANT.auth0.com/authorize",
        "tokenUrl": "https://YOUR_TENANT.auth0.com/oauth/token",
        "scopes": ["mcp:use"],
        "audience": "YOUR_MCP_AUDIENCE"
      }
    }
  }
}

Cursor

Add the following to your Cursor MCP configuration (.cursor/mcp.json):

{
  "mcpServers": {
    "corkboard": {
      "transport": "streamable-http",
      "url": "https://your-instance.example/mcp",
      "headers": {
        "Authorization": "Bearer ${CORKBOARD_MCP_TOKEN}"
      }
    }
  }
}

For Cursor, obtain a token through the OAuth flow and set the CORKBOARD_MCP_TOKEN environment variable. Ensure the token was requested with the mcp:use scope and the correct MCP audience.

Generic HTTP MCP Client

Any MCP-compatible client that speaks Streamable HTTP can connect. The minimal configuration is:

{
  "transport": "streamable-http",
  "url": "https://your-instance.example/mcp",
  "auth": {
    "type": "oauth2",
    "discoveryUrl": "https://your-instance.example/.well-known/oauth-protected-resource/mcp",
    "scopes": ["mcp:use"],
    "audience": "YOUR_MCP_AUDIENCE"
  }
}

Configure your generic client to discover OAuth endpoints from Corkboard's protected resource metadata, then follow the authorization server's OpenID Connect discovery to complete the flow.

← Back to Docs