MCP Servers

See also: MCP Client Setup, Identity and Access, Admin Control Plane, MCP Registry and Discovery

Oceans can register external Streamable HTTP MCP servers and expose them to MCP clients through the gateway at:

/mcp/{server_key}

The gateway authenticates the caller with an Oceans API key, looks up the active registered server, applies any gateway-managed upstream credential, and proxies the MCP Streamable HTTP request to the registered server URL.

Add a Server

Platform admins manage servers in the admin UI:

/admin/mcp/servers

The page supports:

• importing a recommended catalog entry
• adding a custom Streamable HTTP server
• editing display name, URL, auth mode, auth config, and timeout
• disabling a server
• refreshing discovery
• inspecting discovered tools, schema hashes, schema versions, active state, and timestamps

The corresponding admin API surface is documented for maintainers in MCP Registry and Discovery.

Server Keys

server_key is the public path segment clients use in /mcp/{server_key}.

Rules:

• 3 to 64 characters
• lowercase letters, digits, hyphen, and underscore
• stable once clients are configured
• unknown or disabled servers return not found

Auth Modes

Supported stored auth modes are:

• none: no upstream credential is added.
• gateway_static_header: the gateway adds one configured upstream header.
• gateway_bearer_token: the gateway adds an upstream Authorization: Bearer ... header.
• user_passthrough: reserved for future user-scoped credentials.
• oauth_obo: reserved for future OAuth on-behalf-of grants.

Only none, gateway_static_header, and gateway_bearer_token are proxyable today. user_passthrough and oauth_obo return 403 mcp_upstream_auth_required until user-scoped grants exist.

Gateway-Managed Upstream Credentials

Gateway-managed credentials are for the upstream MCP server only. They are not caller credentials and are never returned to admin UI clients.

For gateway_static_header:

{
  "header_name": "X-API-Key",
  "secret_ref": "env/OCEANS_MCP_DISCOVERY_EXAMPLE_KEY"
}

For gateway_bearer_token:

{
  "secret_ref": "env/OCEANS_MCP_DISCOVERY_EXAMPLE_TOKEN"
}

Credentialed modes require an HTTPS server_url. Secret references must use env/OCEANS_MCP_DISCOVERY_*. The environment variable is resolved by the gateway process during discovery and proxying.

Inbound Oceans credentials are always stripped before forwarding upstream. The gateway forwards only MCP protocol/runtime headers plus configured gateway-managed upstream auth.

Discovery

Discovery is the current server health signal.

Refresh discovery from the admin UI after adding or editing a server. Discovery:

• initializes Streamable HTTP
• lists upstream tools
• stores normalized tool schemas
• updates schema hashes and schema versions
• marks missing tools inactive
• records bounded failure summaries

No separate ping health check or discovery-run history UI exists in this slice.