Skip to main content

​
Overview

Superleap exposes a hosted Model Context Protocol (MCP) server for each workspace. Use it to let AI clients securely access Superleap tools on behalf of an authenticated user. Your MCP server URL is based on your Superleap workspace subdomain: 
https://mcp.superleap.com/<subdomain>/mcp
For example, if your workspace is available at apple.superleap.com, use: 
https://mcp.superleap.com/apple/mcp
Replace <subdomain> everywhere in this guide with your workspace subdomain. Do not include .superleap.com in the MCP URL path.

​
Authentication

Superleap MCP uses OAuth 2.0 Authorization Code flow with PKCE. OAuth keeps user authorization separate from API keys and lets MCP clients request access through a standard browser-based consent flow. The OAuth endpoints are hosted on app.superleap.com, not on mcp.superleap.com. The MCP host is the protected resource server; it tells the client which authorization server to use. The typical flow is:
  1. Start with the workspace MCP URL and read its protected-resource metadata.
  2. Discover the workspace OAuth authorization server metadata.
  3. Register the MCP client using Dynamic Client Registration (DCR), if your client does not already have a client_id.
  4. Redirect the user to the workspace authorization endpoint with PKCE and the MCP resource parameter.
  5. Receive the authorization code at the registered callback URL.
  6. Exchange the authorization code for an access token.
  7. Connect to the workspace MCP endpoint with the access token.

​
Step 1: Discover the protected resource

Start from the workspace MCP endpoint. An unauthenticated request returns 401 Unauthorized with a WWW-Authenticate header that points to the protected-resource metadata URL. 
curl -i https://mcp.superleap.com/<subdomain>/mcp
For the apple workspace, the response includes: 
WWW-Authenticate: Bearer resource_metadata=https://mcp.superleap.com/apple/.well-known/oauth-protected-resource
Fetch that metadata URL: 
curl -X GET https://mcp.superleap.com/<subdomain>/.well-known/oauth-protected-resource
For apple, the response looks like: 
{
  "resource": "https://mcp.superleap.com/apple/mcp",
  "authorization_servers": ["https://app.superleap.com/apple"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Superleap CRM MCP Server"
}
​
resource
string
MCP resource URL. Send this exact value as the OAuth resource parameter during authorization.
​
authorization_servers
array
Authorization server identifiers for this workspace. Use the workspace identifier to discover OAuth endpoints.
​
bearer_methods_supported
array
Supported bearer-token delivery methods. Use the Authorization: Bearer <access_token> header.

​
Step 2: Discover OAuth endpoints

Use the workspace authorization server metadata endpoint. The workspace subdomain appears after oauth-authorization-server: 
curl -X GET https://app.superleap.com/.well-known/oauth-authorization-server/<subdomain>
For apple: 
curl -X GET https://app.superleap.com/.well-known/oauth-authorization-server/apple
The response includes the endpoints your client should use: 
{
  "issuer": "https://app.superleap.com",
  "authorization_endpoint": "https://app.superleap.com/api/v1/apple/oauth/authorize",
  "token_endpoint": "https://app.superleap.com/api/v1/apple/oauth/token",
  "registration_endpoint": "https://app.superleap.com/api/v1/apple/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none"],
  "code_challenge_methods_supported": ["S256"]
}
Do not use https://mcp.superleap.com/.well-known/oauth-authorization-server, https://mcp.superleap.com/authorize, https://mcp.superleap.com/token, or https://mcp.superleap.com/register. Those are not the OAuth endpoints for Superleap MCP.
​
issuer
string
OAuth issuer identifier.
​
authorization_endpoint
string
URL where users authorize access. For apple, this is https://app.superleap.com/api/v1/apple/oauth/authorize.
​
token_endpoint
string
URL used to exchange authorization codes and refresh tokens. For apple, this is https://app.superleap.com/api/v1/apple/oauth/token.
​
registration_endpoint
string
Dynamic Client Registration endpoint. For apple, this is https://app.superleap.com/api/v1/apple/oauth/register.
​
response_types_supported
array
Supported OAuth response types. Use code for Authorization Code flow.
​
grant_types_supported
array
Supported grant types, such as authorization_code and refresh_token.
​
token_endpoint_auth_methods_supported
array
Supported token endpoint authentication methods. Public MCP clients use none with PKCE.
​
code_challenge_methods_supported
array
PKCE challenge methods. Use S256 when available.

​
Step 3: Register your MCP client

MCP clients can use Dynamic Client Registration to create a client automatically. Post to the registration_endpoint returned by discovery. 
curl -X POST https://app.superleap.com/api/v1/<subdomain>/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My MCP Client",
    "redirect_uris": [
      "http://localhost:6274/oauth/callback/debug"
    ],
    "grant_types": [
      "authorization_code",
      "refresh_token"
    ],
    "response_types": [
      "code"
    ],
    "token_endpoint_auth_method": "none",
    "client_uri": "https://example.com"
  }'
​
client_name
string
required
Human-readable client name shown during authorization.
​
redirect_uris
array
required
Callback URLs your client can use. The redirect_uri in the authorization request must exactly match one of these values.
​
grant_types
array
required
OAuth grant types requested by the client. Use authorization_code and refresh_token.
​
response_types
array
required
OAuth response types requested by the client. Use code.
​
token_endpoint_auth_method
string
Token endpoint authentication method. Public MCP clients commonly use none with PKCE.
​
client_uri
string
Optional URL for your client application.
A successful registration response returns a client_id: 
{
  "client_id": "<client_id>",
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:6274/oauth/callback/debug"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

​
Step 4: Request user authorization

Redirect the user to the authorization_endpoint returned by the workspace metadata endpoint. Include the resource value from protected-resource discovery. 
https://app.superleap.com/api/v1/<subdomain>/oauth/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&state=<random_state>&code_challenge=<code_challenge>&code_challenge_method=S256&resource=https%3A%2F%2Fmcp.superleap.com%2F<subdomain>%2Fmcp
For apple: 
https://app.superleap.com/api/v1/apple/oauth/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&state=<random_state>&code_challenge=<code_challenge>&code_challenge_method=S256&resource=https%3A%2F%2Fmcp.superleap.com%2Fapple%2Fmcp
Do not hard-code scope=read_only. The current Superleap MCP OAuth metadata does not advertise scopes_supported; use only the parameters returned or required by discovery unless a future metadata response explicitly lists scopes.
​
response_type
string
required
Must be code.
​
client_id
string
required
Client identifier returned during registration.
​
redirect_uri
string
required
Callback URL. Must exactly match one of the registered redirect URIs.
​
state
string
Random value generated by your client to protect against CSRF. Verify the same value is returned in the callback.
​
code_challenge
string
required
PKCE code challenge generated from your code_verifier.
​
code_challenge_method
string
required
Use S256.
​
resource
string
required
The MCP resource URL from protected-resource discovery, for example https://mcp.superleap.com/apple/mcp.
After the user approves access, Superleap redirects to your redirect_uri with a temporary authorization code: 
<redirect_uri>?code=<authorization_code>&state=<random_state>

​
Step 5: Exchange the authorization code for a token

Exchange the authorization code at the token_endpoint returned by discovery. 
curl -X POST https://app.superleap.com/api/v1/<subdomain>/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=<client_id>" \
  -d "code=<authorization_code>" \
  -d "redirect_uri=<redirect_uri>" \
  -d "code_verifier=<code_verifier>" \
  -d "resource=https://mcp.superleap.com/<subdomain>/mcp"
The token response includes:
​
access_token
string
Bearer token used by the MCP client.
​
token_type
string
Token type. Use Bearer.
​
expires_in
integer
Number of seconds before the access token expires.
​
refresh_token
string
Token used to request a new access token when refresh tokens are enabled for the client.

​
Step 6: Connect your MCP client

Configure your MCP client with your workspace MCP endpoint: 
https://mcp.superleap.com/<subdomain>/mcp
For a workspace at apple.superleap.com: 
https://mcp.superleap.com/apple/mcp
The MCP client should send the OAuth access token as a Bearer token when connecting: 
curl -X POST https://mcp.superleap.com/apple/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "my-mcp-client",
        "version": "1.0.0"
      }
    }
  }'
Most MCP clients handle the OAuth flow, token storage, and MCP protocol messages automatically. In that case, you only need to provide the server URL: https://mcp.superleap.com/<subdomain>/mcp.

​
Example: Connect with Hermes Agent

Hermes Agent supports OAuth-protected remote MCP servers. Add the Superleap MCP server with the workspace MCP URL: 
hermes mcp add superleap_<subdomain> --url https://mcp.superleap.com/<subdomain>/mcp --auth oauth
hermes mcp login superleap_<subdomain>
For apple: 
hermes mcp add superleap_apple --url https://mcp.superleap.com/apple/mcp --auth oauth
hermes mcp login superleap_apple
Hermes will perform the discovery and Dynamic Client Registration steps automatically, then print an authorization URL. Open that URL in your browser, approve access, and complete the OAuth redirect. If Hermes is running on a remote machine, in Slack, or in another headless environment, the browser may not be able to call the local callback URL directly. In that case:
  1. Ask Hermes to connect to the Superleap MCP server.
  2. Hermes should give you the authorization URL.
  3. Open the authorization URL in your browser and approve access.
  4. When the browser lands on the final http://127.0.0.1:<port>/callback?code=...&state=... return URL, copy the full URL from the browser address bar.
  5. Paste that full return URL back to Hermes so it can exchange the code for tokens.
Keep the Hermes login process running while you approve access and paste back the return URL. The authorization code, state, and PKCE verifier are tied to that live OAuth attempt.

​
Token management

  • Store access tokens and refresh tokens securely. Do not commit tokens to version control.
  • Track expires_in and refresh tokens before they expire.
  • Use PKCE for browser, desktop, CLI, and other public clients.
  • Validate the state parameter on every OAuth callback.
  • Re-run OAuth authorization if the user revokes access or the refresh token expires.

​
Troubleshooting

IssueWhat to check
https://mcp.superleap.com/.well-known/oauth-authorization-server returns 404This is expected. Discover OAuth metadata from https://app.superleap.com/.well-known/oauth-authorization-server/<subdomain> after reading the protected-resource metadata from the MCP URL.
Authorization URL on mcp.superleap.com does not workUse the authorization_endpoint on app.superleap.com, for example https://app.superleap.com/api/v1/apple/oauth/authorize.
invalid_redirect_uriThe authorization request redirect_uri must exactly match a URI registered in redirect_uris.
invalid_clientConfirm you are using the latest client_id from registration and the correct workspace-specific endpoints.
invalid_grantAuthorization codes are single-use and expire quickly. Restart the authorization flow.
401 Unauthorized from MCPConfirm the Authorization: Bearer <access_token> header is present and the token is not expired.
Workspace not foundConfirm the MCP URL uses only the workspace subdomain, for example /apple/mcp for apple.superleap.com.