> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superleap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to Superleap MCP

> Connect MCP clients to your Superleap workspace using OAuth 2.0.

## 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:

```text theme={null}
https://mcp.superleap.com/<subdomain>/mcp
```

For example, if your workspace is available at `apple.superleap.com`, use:

```text theme={null}
https://mcp.superleap.com/apple/mcp
```

<Info>
  Replace `<subdomain>` everywhere in this guide with your workspace subdomain. Do not include `.superleap.com` in the MCP URL path.
</Info>

## 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.

```bash theme={null}
curl -i https://mcp.superleap.com/<subdomain>/mcp
```

For the `apple` workspace, the response includes:

```text theme={null}
WWW-Authenticate: Bearer resource_metadata=https://mcp.superleap.com/apple/.well-known/oauth-protected-resource
```

Fetch that metadata URL:

```bash theme={null}
curl -X GET https://mcp.superleap.com/<subdomain>/.well-known/oauth-protected-resource
```

For `apple`, the response looks like:

```json theme={null}
{
  "resource": "https://mcp.superleap.com/apple/mcp",
  "authorization_servers": ["https://app.superleap.com/apple"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Superleap CRM MCP Server"
}
```

<ResponseField name="resource" type="string">
  MCP resource URL. Send this exact value as the OAuth `resource` parameter during authorization.
</ResponseField>

<ResponseField name="authorization_servers" type="array">
  Authorization server identifiers for this workspace. Use the workspace identifier to discover OAuth endpoints.
</ResponseField>

<ResponseField name="bearer_methods_supported" type="array">
  Supported bearer-token delivery methods. Use the `Authorization: Bearer <access_token>` header.
</ResponseField>

## Step 2: Discover OAuth endpoints

Use the workspace authorization server metadata endpoint. The workspace subdomain appears after `oauth-authorization-server`:

```bash theme={null}
curl -X GET https://app.superleap.com/.well-known/oauth-authorization-server/<subdomain>
```

For `apple`:

```bash theme={null}
curl -X GET https://app.superleap.com/.well-known/oauth-authorization-server/apple
```

The response includes the endpoints your client should use:

```json theme={null}
{
  "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"]
}
```

<Warning>
  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.
</Warning>

<ResponseField name="issuer" type="string">
  OAuth issuer identifier.
</ResponseField>

<ResponseField name="authorization_endpoint" type="string">
  URL where users authorize access. For `apple`, this is `https://app.superleap.com/api/v1/apple/oauth/authorize`.
</ResponseField>

<ResponseField name="token_endpoint" type="string">
  URL used to exchange authorization codes and refresh tokens. For `apple`, this is `https://app.superleap.com/api/v1/apple/oauth/token`.
</ResponseField>

<ResponseField name="registration_endpoint" type="string">
  Dynamic Client Registration endpoint. For `apple`, this is `https://app.superleap.com/api/v1/apple/oauth/register`.
</ResponseField>

<ResponseField name="response_types_supported" type="array">
  Supported OAuth response types. Use `code` for Authorization Code flow.
</ResponseField>

<ResponseField name="grant_types_supported" type="array">
  Supported grant types, such as `authorization_code` and `refresh_token`.
</ResponseField>

<ResponseField name="token_endpoint_auth_methods_supported" type="array">
  Supported token endpoint authentication methods. Public MCP clients use `none` with PKCE.
</ResponseField>

<ResponseField name="code_challenge_methods_supported" type="array">
  PKCE challenge methods. Use `S256` when available.
</ResponseField>

## 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.

```bash theme={null}
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"
  }'
```

<ParamField body="client_name" type="string" required>
  Human-readable client name shown during authorization.
</ParamField>

<ParamField body="redirect_uris" type="array" required>
  Callback URLs your client can use. The `redirect_uri` in the authorization request must exactly match one of these values.
</ParamField>

<ParamField body="grant_types" type="array" required>
  OAuth grant types requested by the client. Use `authorization_code` and `refresh_token`.
</ParamField>

<ParamField body="response_types" type="array" required>
  OAuth response types requested by the client. Use `code`.
</ParamField>

<ParamField body="token_endpoint_auth_method" type="string">
  Token endpoint authentication method. Public MCP clients commonly use `none` with PKCE.
</ParamField>

<ParamField body="client_uri" type="string">
  Optional URL for your client application.
</ParamField>

A successful registration response returns a `client_id`:

```json theme={null}
{
  "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.

```text theme={null}
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`:

```text theme={null}
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
```

<Note>
  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.
</Note>

<ParamField query="response_type" type="string" required>
  Must be `code`.
</ParamField>

<ParamField query="client_id" type="string" required>
  Client identifier returned during registration.
</ParamField>

<ParamField query="redirect_uri" type="string" required>
  Callback URL. Must exactly match one of the registered redirect URIs.
</ParamField>

<ParamField query="state" type="string">
  Random value generated by your client to protect against CSRF. Verify the same value is returned in the callback.
</ParamField>

<ParamField query="code_challenge" type="string" required>
  PKCE code challenge generated from your `code_verifier`.
</ParamField>

<ParamField query="code_challenge_method" type="string" required>
  Use `S256`.
</ParamField>

<ParamField query="resource" type="string" required>
  The MCP resource URL from protected-resource discovery, for example `https://mcp.superleap.com/apple/mcp`.
</ParamField>

After the user approves access, Superleap redirects to your `redirect_uri` with a temporary authorization code:

```text theme={null}
<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.

```bash theme={null}
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:

<ResponseField name="access_token" type="string">
  Bearer token used by the MCP client.
</ResponseField>

<ResponseField name="token_type" type="string">
  Token type. Use `Bearer`.
</ResponseField>

<ResponseField name="expires_in" type="integer">
  Number of seconds before the access token expires.
</ResponseField>

<ResponseField name="refresh_token" type="string">
  Token used to request a new access token when refresh tokens are enabled for the client.
</ResponseField>

## Step 6: Connect your MCP client

Configure your MCP client with your workspace MCP endpoint:

```text theme={null}
https://mcp.superleap.com/<subdomain>/mcp
```

For a workspace at `apple.superleap.com`:

```text theme={null}
https://mcp.superleap.com/apple/mcp
```

The MCP client should send the OAuth access token as a Bearer token when connecting:

```bash theme={null}
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"
      }
    }
  }'
```

<Note>
  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`.
</Note>

## Example: Connect with Hermes Agent

Hermes Agent supports OAuth-protected remote MCP servers. Add the Superleap MCP server with the workspace MCP URL:

```bash theme={null}
hermes mcp add superleap_<subdomain> --url https://mcp.superleap.com/<subdomain>/mcp --auth oauth
hermes mcp login superleap_<subdomain>
```

For `apple`:

```bash theme={null}
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

| 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`.                                                                                    |