Skip to main content
Register your own custom REST/HTTP API at runtime. Point RouteMCP at a base URL, optionally give it an OpenAPI spec, and it generates one typed tool per operation, embeds them for search, 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.
This is the REST-API sibling of Bring Your Own MCP. Use BYO Integration for a plain HTTP/REST API described by an OpenAPI spec; use BYO MCP for a server that speaks the Model Context Protocol.

​
How it works

1

Register the API

In the dashboard, open Integrations → Add custom integration. Provide a name, the base URL (host only — e.g. https://api.example.com), optionally an OpenAPI spec URL, and its authentication (see below).
2

Pick tools from a spec — or a passthrough tool

  • With a spec → RouteMCP parses it and generates one tool per operation.
  • Without a spec → it registers a single generic <SLUG>_CALL(method, path, query, body) tool the agent drives directly. Good for quick, spec-less APIs.
3

Authenticate (OAuth only)

For OAuth integrations, click Connect after saving to complete the authorization handshake. none / API key / bearer are ready immediately.
4

Use it

The toolkit appears in your catalog. Attach it to a workspace and call it from the chat endpoint, or explore it in the playground — see Using your integration.

​
The OpenAPI spec

RouteMCP generates tools from an OpenAPI/Swagger spec (JSON or YAML). You can supply it as a spec URL, and for recognized providers the URL is filled in for you from just the base URL — for example, typing https://app.asana.com auto-fills Asana’s published spec, and typing an Atlassian, Slack, Box, Xero, Spotify, or PayPal host does the same for theirs.
A documentation page is not a spec. RouteMCP needs the machine-readable OpenAPI file (a .json/.yaml URL), not the human docs page that lists endpoints or scopes — those can’t be parsed. If you paste a docs page, you’ll get a clear error pointing you to the spec file.
Leave the spec blank for a single passthrough tool. Passthrough calls default to a JSON body; for APIs that require application/x-www-form-urlencoded (e.g. Stripe), pass "bodyFormat": "form" in the tool arguments.

​
Ownership

Choose per integration:
  • Personal — only you can see and use it.
  • Shared — usable by everyone in your organization.
Credentials — including OAuth tokens — are stored per integration, not per user. On a shared integration, whoever clicks Connect authorizes once and every member calls the upstream API as that account. Use personal ownership if each member should act as themselves.

​
Authentication

Pick one auth type when registering. All credentials are encrypted at rest.
Non-standard credential headers are supported. Set the header name and prefix — e.g. Zoho Books uses Authorization: Zoho-oauthtoken <token>.

​
OAuth 2.0 & scopes

Custom integrations don’t support OAuth auto-discovery, so you enter the Client ID, the provider’s Authorization URL and Token URL, and the scopes to request. When the integration has an OpenAPI spec that declares scopes, RouteMCP shows a scope picker instead of a free-text box: search, tick the scopes you need, and (for recognized hosts with curated defaults) start from a recommended set. A Select all control and a manual-add field are there too, so you’re never limited to what the spec happened to declare.
Scopes must also be enabled in the provider’s own developer console (e.g. Asana’s OAuth app settings). RouteMCP can’t check that for you — if the connect screen reports a forbidden scope, enable it there, then reconnect.
Scope strings are case- and format-sensitive. Most providers use a colon (users:read), not a dot. Copy them exactly as the provider documents them.
After saving an OAuth integration, click Connect — you’ll be redirected to the provider to authorize, then returned to the dashboard.
Add RouteMCP’s callback to your OAuth app’s Authorized redirect URIs: https://api.routemcp.io/api/v1/connect/oauth/callback

​
Using your integration in chat

A registered integration becomes a toolkit identified by a toolkit slug (chttp_<name>_<hash>). As with any toolkit, you attach it to a workspace, then chat with that workspace.
1

Attach the toolkit to a workspace

In the dashboard, add the toolkit to a workspace’s integrations. Or via the API, pass its slug in integrations:
Omit integrations (or pass []) to expose all of your org’s toolkits — your custom integration included.
2

Chat with the workspace

Call the chat endpoint with the workspace’s serverId:
The agent discovers your integration’s tools via SEARCH_TOOLS and runs them via MULTI_EXECUTE_TOOL, wrapped in the platform’s resilience stack.

​
Managing an integration

From the integration’s ⋯ menu on the Integrations page:
  • Edit — update the name, base URL, docs URL, and ownership. These take effect immediately (tools use paths relative to the base URL, so no re-import is needed). Auth type, spec, and credentials can’t be changed in place — remove and re-add to change those.
  • Edit scopes (OAuth) — add or remove requested scopes. Saving sets the integration back to pending; reconnect to grant the new set.
  • Remove — deletes the integration and archives its tools.

​
Insufficient-scope errors

If a tool call is refused for a missing OAuth scope, RouteMCP returns a precise, actionable message: it names the exact scope needed and the scopes the connection currently grants, and hands the agent the reconnect step. If the connection already grants every scope the spec expects but the call still fails, that’s usually a scope not enabled in the provider’s developer console — the message says so, rather than guessing.

​
Notes & limits

  • Hybrid tools — a spec generates typed tools (capped at 200 per integration; overflow is logged, never silently dropped); no spec gives one generic passthrough tool.
  • Resilience — every call goes through the same circuit breaker, rate limiting, retry, and timeout stack as built-in integrations.
  • Security — credentials are encrypted at rest and never returned to the browser; upstream error bodies are surfaced to the agent so failures are diagnosable.