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

# Bring Your Own MCP

> Register any external MCP server by URL — RouteMCP catalogs its tools and exposes them as a first-class toolkit your agents can use.

Register your own **external MCP server** by URL. RouteMCP connects out to it as an MCP
**client**, introspects everything it exposes (tools and their schemas), enriches and embeds
them, and materializes the result as a **first-class toolkit** in your catalog — usable in the
playground, the router, and the chat completion endpoint, just like a built-in integration
(HubSpot, Postgres, etc.).

<Info>
  Bring Your Own MCP is **shared / org-level**: you supply one credential at registration and it's
  reused for every call your agents make to that server. (There is no per-end-user connection
  for custom servers — that flow is reserved for unified-API integrations.)
</Info>

## How it works

<Steps>
  <Step title="Register the server">
    In the dashboard, go to **Bring Your Own MCP → Add MCP server**. Provide a name, the server URL, and
    its authentication (see below). RouteMCP validates the URL (SSRF-guarded) and saves it.
  </Step>

  <Step title="Authenticate (OAuth only)">
    For OAuth servers, click **Connect** after saving to complete the authorization handshake.
    Servers using `none` / API key / bearer are ready immediately.
  </Step>

  <Step title="Cataloging">
    RouteMCP introspects the server, classifies each tool's risk, and embeds it for search. The
    discovered tools appear under **Discovered tools**, each with an enable/disable toggle.
  </Step>

  <Step title="Use it">
    Add the toolkit to a workspace and call it from the chat endpoint, or explore it in the
    playground. See [Using your server](#using-your-server-in-chat).
  </Step>
</Steps>

## Authentication

Pick one auth type when registering. All credentials are encrypted at rest.

| Auth type        | When to use                             | What you provide                                 |
| ---------------- | --------------------------------------- | ------------------------------------------------ |
| **None**         | Public servers, no credentials          | —                                                |
| **API key**      | A static key sent in a custom header    | The key + header name (defaults to `X-API-Key`)  |
| **Bearer token** | A static long-lived token               | The token (sent as `Authorization: Bearer …`)    |
| **OAuth 2.0**    | Servers that require an OAuth handshake | Client ID/Secret (optional) + scopes (see below) |

### OAuth 2.0

RouteMCP implements the MCP authorization spec (OAuth 2.1 + PKCE). When you choose OAuth, two
flavours are supported from the same form:

<CardGroup cols={2}>
  <Card title="Dynamic Client Registration" icon="wand-magic-sparkles">
    **Leave Client ID & Secret blank.** If the server advertises a registration endpoint
    (RFC 7591), RouteMCP registers a client automatically. Example: **ClickUp**.
  </Card>

  <Card title="Pre-registered app" icon="key">
    **Fill in Client ID & Secret** from an OAuth app you created on the provider. Required when
    the server has no DCR. Examples: **Google Chat**, **GitHub**.
  </Card>
</CardGroup>

<Note>
  **Scopes** — some providers (e.g. Google) don't advertise scopes and require them explicitly.
  Enter space-separated scopes in the **Scopes** field when registering. You can also override
  the **Authorization URL** / **Token URL** if the server's endpoints can't be auto-discovered.
</Note>

After saving an OAuth server, click **Connect** — you'll be redirected to the provider to
authorize, then returned to the dashboard. Cataloging starts automatically once the token is
stored.

<Warning>
  For pre-registered OAuth apps, add RouteMCP's callback to your app's **Authorized redirect
  URIs**:
  `https://<your-api-host>/api/v1/connect/oauth/callback`
</Warning>

## Using your server in chat

A registered MCP server becomes a **toolkit** identified by a **toolkit slug** (shown on the server
detail card, with a copy button). The chat endpoint is addressed by a **workspace `serverId`**,
not the toolkit slug — so you attach the toolkit to a workspace, then chat with that workspace.

<Steps>
  <Step title="Attach the toolkit to a workspace">
    In the dashboard, add the toolkit to a workspace's integrations (pick it by name). Or via the
    API, pass its slug in `integrations`:

    ```bash theme={null}
    curl -X POST https://<your-api-host>/api/v1/mcp/workspaces \
      -H "Authorization: Bearer $ROUTEMCP_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "name": "My workspace", "integrations": ["xmcp_clickup_d4c66fa7"] }'
    ```

    <Tip>Omit `integrations` (or pass `[]`) to expose **all** of your org's toolkits — your custom server included.</Tip>
  </Step>

  <Step title="Chat with the workspace">
    Call the chat endpoint with the workspace's `serverId`:

    ```bash theme={null}
    curl -X POST https://<your-api-host>/api/v1/mcp/{serverId}/chat \
      -H "Authorization: Bearer $ROUTEMCP_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "message": "List my ClickUp spaces" }'
    ```

    The agent discovers your server's tools via `SEARCH_TOOLS` and runs them via
    `MULTI_EXECUTE_TOOL`, wrapped in the platform's resilience stack.
  </Step>
</Steps>

## Managing a server

* **Re-sync** — re-introspect the server to pick up new or changed tools. Available once the
  server is connected and catalogued.
* **Enable / disable tools** — toggle individual tools from the discovered-tools list to control
  what agents can call.
* **Delete** — removes the server and archives its toolkit. The dashboard warns you which
  workspaces reference it before you confirm.

## Notes & limits

* **Shared-only.** One org-level credential per server, reused for all end-users.
* **Transport** is auto-detected (Streamable HTTP or SSE).
* **Resilience** — every call goes through the same circuit breaker, rate limiting, retry, and
  timeout stack as built-in integrations.
* **Security** — server URLs are SSRF-validated; tool errors returned to the agent are scrubbed
  of secret-looking values.