Switchy
Open app
Guide

Custom MCP

Any HTTPS MCP server can be registered in Switchy by URL. Useful for internal tools, third-party MCPs we don't have a one-click connector for, or self-hosted servers.

Prerequisites

  • An MCP server reachable over HTTPS. http:// is rejected; localhost and private IPs are rejected.
  • An auth method: a bearer token OR an API key (custom header). OAuth lands as a separate path via the connector registry; raw OAuth is not yet supported for custom servers.
  • Org admin role (the registration API requires it).

Register

  1. Open Settings → MCP integrations.
  2. Scroll past the one-click cards to Add a custom MCP.
  3. Fill in:
    • Display name — what teammates see in lists.
    • Mention slug — what they type after @. Lowercase, alphanumeric + dashes/underscores. Must be unique in the org.
    • Endpoint URL — must be HTTPS.
    • Auth type — None, Bearer token, or API key (custom header).
    • Secret — for Bearer, the raw token. For API key, the format HeaderName:value (e.g. X-Api-Key:sk_xxx).
  4. Click Connect MCP. The credential is written to Google Secret Manager before the DB row is created; if Secret Manager fails, no orphan rows.
  5. Click Test on the new row to confirm the upstream responds. We call its initialize method and report success or the exact failure code.

Bind to a Space

Same as the one-click connectors: open the Space → Settings → MCP integrations → toggle your slug on.

Network safety

The SSRF guard runs at registration AND on every call (DNS rebinding defence). It rejects:

  • Anything that isn't HTTPS.
  • Privileged ports other than 443.
  • Literal private IPs / localhost / *.local / *.internal / metadata.google.internal.
  • Hostnames that DNS-resolve to RFC1918, loopback, link-local (incl. 169.254.169.254), CGNAT, multicast, or v6 unique-local / link-local / multicast / v4-mapped-private.

Outbound discipline

  • HTTPS-only. No HTTP fallback.
  • Redirects are not followed. A 30x to a private IP would slip past the SSRF guard, so we refuse.
  • Outbound body capped at 50 KB; inbound body capped at 5 MB.
  • Per-call timeout: 10s for tool calls, 30s for the MCP handshake.
  • Custom User-Agent: switchy-mcp-client/0.1.0.

What your MCP needs to support

Switchy speaks JSON-RPC 2.0 over HTTPS. Your server needs to handle:

  • initialize — returns serverInfo + capabilities. Used by Switchy's test-connection + health probes.
  • tools/call — accepts { name, arguments } and returns either { structuredContent } or { content: [...] }.

MCP's reference TypeScript SDK and Python SDK both ship HTTP server scaffolding that gets you a compliant server in a few lines.

Health checks

Cloud Scheduler probes every active MCP every 10 minutes. Status flows: HEALTHY (under 5s), DEGRADED (5–30s), UNREACHABLE (failed or over 30s). Org OWNERS get one email per day per integration on transition to UNREACHABLE.

Next

←PreviousConnect NotionNextTeam billing→