---
title: "Bring your own MCP server or API"
description: "Connect a public MCP server, import OpenAPI JSON, or define REST operations, then review and publish tools for your workspace."
---

Owners and admins can add their own endpoints from **Connections → Your MCP
servers and APIs → Add your own**. The same entry is available in guided setup.
A draft makes no tools available to agents.

## Connect and publish

1. Choose **MCP server**, **OpenAPI document**, or **REST operations**. Enter a
   display name, a unique lowercase tool namespace, and the endpoint including
   its base path.
2. Choose no authentication, bearer token, one named API-key header, or Basic.
   Save the draft, then enter credentials in the separate write-only form.
   The gateway seals the credential; the dashboard never receives it back.
3. Discover tools for MCP or a public OpenAPI document URL. Uploads, pasted JSON,
   and manual REST operations compile without network discovery. Metadata
   discovery never calls a tool or tests a mutation.
4. Select each tool deliberately and choose **Read only** or **Destructive
   action**. Check its schemas and request encoding, then save the review.
5. Review added, changed, and removed tools. Acknowledge that existing broad key
   scopes and policies may already permit these tools, then publish. Wait for
   the gateway publication to finish.
6. Configure an [application virtual key](/security/virtual-keys), make a call
   through [Obol MCP](/gateway/mcp), and inspect its [receipt](/receipts/overview).
   Publishing does not change key scopes, policies, budgets, or approval rules.

## Supported inputs

| Input | Supported subset |
|---|---|
| MCP | Streamable HTTP; protocol 2025-03-26, 2025-06-18, or 2025-11-25; paginated tool discovery |
| OpenAPI | 3.0.0–3.0.4 JSON; upload, paste, or a public document URL; bounded local schema references |
| REST | GET, POST, PUT, PATCH, DELETE; fixed relative paths and explicit schemas |
| Bodies | JSON or reviewed URL-encoded forms with flat scalar fields |
| Authentication | None, bearer, one safe API-key header, or Basic |

Endpoints must use public DNS names and HTTPS port 443. Redirects, private
addresses, endpoint overrides, and credentials embedded in URLs are refused.
An OpenAPI document URL is fetched without credentials; upload private documents.

The initial subset excludes OpenAPI 3.1, YAML, external references, schema
composition, nullable unions, multipart uploads, cookie parameters, and complex
path/query/header serialization. Forms must constrain every field to a scalar
value, including extra properties. Numeric 2xx and `2XX` response schemas are
supported; schema-bearing `default` responses are refused. Unsupported operations
are diagnosed during import. Defaults and examples are discarded.

Source and aggregate discovery metadata are limited to 2 MiB, with 128 tools,
20 MCP pages, and 64 KiB per schema. Discovery has a 20-second deadline. Each
workspace can run one discovery at a time and start ten attempts per minute.
Unpublished drafts expire after seven days.

## Refresh and recovery

**Create refresh candidate** keeps the published revision live while you replace
its source or discover again. Review and publish the changes explicitly. The
endpoint, namespace, source kind, and authentication method become fixed after
first publication; changing them requires another connector.

A retained revision can be reviewed and published again. Disabling removes tools
from the gateway snapshot. **Start a fresh draft** prepares a disabled connection
for another review and publication. Credential rotation also takes the connection
out of service until it is reviewed and republished. Cancelled or expired
unpublished source must be provided again.

## What a receipt proves

Direct REST calls are native with **gateway-observed** evidence. A reviewed
custom mutation without configured verification remains **inconclusive**, even
when the API returns HTTP 200. Remote MCP is federated with **untrusted** evidence,
even when Obol vaults its token. Server annotations cannot change that class.

[Production approvals](/policy/approvals), virtual-key scopes, policy decisions,
Obol idempotency, receipts, and metering apply to custom calls through the ordinary
gateway path. Discovery does not grant execution authority.