API · 2.0.0

MCP

External MCP integrations bound to Spaces.

4 operations. All requests need Authorization: Bearer sk_.... Responses use the standard envelope; see overview for shapes and error codes.

get/mcp/servers

List MCP integrations registered in the org

Responses

200 — MCP servers.
400 — Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
401 — Missing or invalid auth. `error.code = AUTH_ERROR`.
403 — Authenticated but not allowed (wrong role, not a member, or org scope mismatch). `error.code = FORBIDDEN`.
404 — Resource does not exist or is invisible to the caller. `error.code = NOT_FOUND`.
409 — Conflict — duplicate slug, race condition, or invalid state transition. `error.code = CONFLICT`.
429 — Rate limit exceeded. `error.code = RATE_LIMIT`. Retry after the window listed in `Retry-After`.
500 — Unexpected server error. `error.code = INTERNAL_ERROR`. Logged with the `requestId` echoed in metadata.

cURL example

curl -X GET https://switchy.build/api/mcp/servers \
  -H 'Authorization: Bearer sk_live_...' \

post/mcp/servers

Register a custom MCP server

HTTPS-only. Endpoint is checked against the SSRF guard at registration AND on every call.

Request body

Field	Type	Required	Description
`displayName`	`string`	yes
`mentionSlug`	`string`	yes	Lowercase, alphanumeric + dashes/underscores. Unique per org.
`endpointUrl`	`string (uri)`	yes	Must be HTTPS.
`authType`	`"NONE" \| "BEARER" \| "API_KEY"`	yes
`secret`	`string`	no	Bearer token, or `HeaderName:value` for API_KEY.

Responses

201 — Created server.
400 — Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
401 — Missing or invalid auth. `error.code = AUTH_ERROR`.
403 — Authenticated but not allowed (wrong role, not a member, or org scope mismatch). `error.code = FORBIDDEN`.
404 — Resource does not exist or is invisible to the caller. `error.code = NOT_FOUND`.
409 — Conflict — duplicate slug, race condition, or invalid state transition. `error.code = CONFLICT`.
429 — Rate limit exceeded. `error.code = RATE_LIMIT`. Retry after the window listed in `Retry-After`.
500 — Unexpected server error. `error.code = INTERNAL_ERROR`. Logged with the `requestId` echoed in metadata.

cURL example

curl -X POST https://switchy.build/api/mcp/servers \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

delete/mcp/servers/{id}

Remove an MCP integration

Parameters

Name	In	Required	Type	Description
`id`	path	yes	`string`	CUID

Responses

204 — Removed; secret deleted from Secret Manager.
400 — Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
401 — Missing or invalid auth. `error.code = AUTH_ERROR`.
403 — Authenticated but not allowed (wrong role, not a member, or org scope mismatch). `error.code = FORBIDDEN`.
404 — Resource does not exist or is invisible to the caller. `error.code = NOT_FOUND`.
409 — Conflict — duplicate slug, race condition, or invalid state transition. `error.code = CONFLICT`.
429 — Rate limit exceeded. `error.code = RATE_LIMIT`. Retry after the window listed in `Retry-After`.
500 — Unexpected server error. `error.code = INTERNAL_ERROR`. Logged with the `requestId` echoed in metadata.

cURL example

curl -X DELETE https://switchy.build/api/mcp/servers/:id \
  -H 'Authorization: Bearer sk_live_...' \

post/mcp/servers/{id}/test-connection

Test an MCP server

Calls `initialize` on the upstream and reports the result. Used by the UI test button.

Parameters

Name	In	Required	Type	Description
`id`	path	yes	`string`	CUID

Responses

200 — Result.
400 — Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
401 — Missing or invalid auth. `error.code = AUTH_ERROR`.
403 — Authenticated but not allowed (wrong role, not a member, or org scope mismatch). `error.code = FORBIDDEN`.
404 — Resource does not exist or is invisible to the caller. `error.code = NOT_FOUND`.
409 — Conflict — duplicate slug, race condition, or invalid state transition. `error.code = CONFLICT`.
429 — Rate limit exceeded. `error.code = RATE_LIMIT`. Retry after the window listed in `Retry-After`.
500 — Unexpected server error. `error.code = INTERNAL_ERROR`. Logged with the `requestId` echoed in metadata.

cURL example

curl -X POST https://switchy.build/api/mcp/servers/:id/test-connection \
  -H 'Authorization: Bearer sk_live_...' \