Connect to Superleap MCP

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:

Start with the workspace MCP URL and read its protected-resource metadata.
Discover the workspace OAuth authorization server metadata.
Register the MCP client using Dynamic Client Registration (DCR), if your client does not already have a client_id.
Redirect the user to the workspace authorization endpoint with PKCE and the MCP resource parameter.
Receive the authorization code at the registered callback URL.
Exchange the authorization code for an access token.
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"
}

string

MCP resource URL. Send this exact value as the OAuth resource parameter during authorization.

array

Authorization server identifiers for this workspace. Use the workspace identifier to discover OAuth endpoints.

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.

string

OAuth issuer identifier.

string

URL where users authorize access. For apple, this is https://app.superleap.com/api/v1/apple/oauth/authorize.

string

URL used to exchange authorization codes and refresh tokens. For apple, this is https://app.superleap.com/api/v1/apple/oauth/token.

string

Dynamic Client Registration endpoint. For apple, this is https://app.superleap.com/api/v1/apple/oauth/register.

array

Supported OAuth response types. Use code for Authorization Code flow.

array

Supported grant types, such as authorization_code and refresh_token.

array

Supported token endpoint authentication methods. Public MCP clients use none with PKCE.

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"
  }'

string

required

Human-readable client name shown during authorization.

array

required

Callback URLs your client can use. The redirect_uri in the authorization request must exactly match one of these values.

array

required

OAuth grant types requested by the client. Use authorization_code and refresh_token.

array

required

OAuth response types requested by the client. Use code.

string

Token endpoint authentication method. Public MCP clients commonly use none with PKCE.

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.

string

required

Must be code.

string

required

Client identifier returned during registration.

string

required

Callback URL. Must exactly match one of the registered redirect URIs.

string

Random value generated by your client to protect against CSRF. Verify the same value is returned in the callback.

string

required

PKCE code challenge generated from your code_verifier.

string

required

Use S256.

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:

string

Bearer token used by the MCP client.

string

Token type. Use Bearer.

integer

Number of seconds before the access token expires.

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:

Ask Hermes to connect to the Superleap MCP server.
Hermes should give you the authorization URL.
Open the authorization URL in your browser and approve access.
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.
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

Issue	What to check
`https://mcp.superleap.com/.well-known/oauth-authorization-server` returns `404`	This 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 work	Use the `authorization_endpoint` on `app.superleap.com`, for example `https://app.superleap.com/api/v1/apple/oauth/authorize`.
`invalid_redirect_uri`	The authorization request `redirect_uri` must exactly match a URI registered in `redirect_uris`.
`invalid_client`	Confirm you are using the latest `client_id` from registration and the correct workspace-specific endpoints.
`invalid_grant`	Authorization codes are single-use and expire quickly. Restart the authorization flow.
`401 Unauthorized` from MCP	Confirm the `Authorization: Bearer <access_token>` header is present and the token is not expired.
Workspace not found	Confirm the MCP URL uses only the workspace subdomain, for example `/apple/mcp` for `apple.superleap.com`.

​Overview

​Authentication

​Step 1: Discover the protected resource

​Step 2: Discover OAuth endpoints

​Step 3: Register your MCP client

​Step 4: Request user authorization

​Step 5: Exchange the authorization code for a token

​Step 6: Connect your MCP client

​Example: Connect with Hermes Agent

​Token management

​Troubleshooting

Overview

Authentication

Step 1: Discover the protected resource

Step 2: Discover OAuth endpoints

Step 3: Register your MCP client

Step 4: Request user authorization

Step 5: Exchange the authorization code for a token

Step 6: Connect your MCP client

Example: Connect with Hermes Agent

Token management

Troubleshooting