MCP connections
Overview
MCP Connections are Tenant configuration for remote Streamable HTTP tool servers and do not carry Attribution. Use these endpoints to store write-only credentials, inspect definitions, test connectivity, or complete reconnection and OAuth setup without exposing secrets.
Endpoints
POST /v1/mcp-connections
Creates a reusable MCP Connection. MCP Connections are Tenant configuration and do not carry Attribution.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Location | Field | Required | Description |
|---|---|---|---|
| Body | name | yes | Unique display name. |
| Body | url | yes | Remote Streamable HTTP URL. |
| Body | authType | yes | none, bearer, oauth_client_credentials, or oauth_authorization_code; credentials depend on the discriminant. |
| Body | bearerToken | conditional | Required only for bearer. |
| Body | clientId | conditional | Required with clientSecret for client credentials; optional but paired for authorization code. |
| Body | clientSecret | conditional | Required with clientId for client credentials; optional but paired for authorization code. |
| Body | scope | no | Optional OAuth scope for either OAuth mode. |
| Header | Content-Type | yes | application/json. |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
201 Created | McpConnectionResponse | Stores a connected definition, or needs_auth for authorization-code OAuth; secrets remain write-only. |
For none, bearer, and client-credentials authentication, create validates the live server before committing and returns connected. Authorization-code create does not contact the upstream server; it stores needs_auth for the admin-session connect flow.
Response schema: mcpConnectionResponseSchema.
Errors
400 invalid_request for an invalid discriminated body, unsafe URL, OAuth discovery failure, rejected credentials, or unreachable/invalid server. A duplicate name returns exactly 409 invalid_request. A failed create does not retain the staged connection. See REST errors.
cURL
curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/mcp-connections" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"Docs","url":"https://mcp.example.com/mcp","authType":"none"}'SDK and related guides
SDK: create. See MCP Connections and Connect an MCP server.
GET /v1/mcp-connections
Lists the Tenant's MCP Connections. MCP Connections are Tenant configuration and do not carry Attribution.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
200 OK | McpConnectionsResponse | Read-only; secrets are redacted. |
Response schema: mcpConnectionsResponseSchema.
Errors
Authentication and service errors only. See REST errors.
cURL
curl "$BLAZING_AGENTS_BASE_URL/v1/mcp-connections" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"SDK and related guides
SDK: list. See MCP Connections and Connect an MCP server.
GET /v1/mcp-connections/:id
Gets one MCP Connection. MCP Connections are Tenant configuration and do not carry Attribution.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Path | id | yes | MCP Connection ID. |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
200 OK | McpConnectionResponse | Read-only; credentials are redacted. |
Response schema: mcpConnectionResponseSchema.
Errors
404 not_found for an unknown or out-of-Tenant ID. See REST errors.
cURL
curl "$BLAZING_AGENTS_BASE_URL/v1/mcp-connections/mcp_1234567890ABCDEF" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"SDK and related guides
SDK: get. See MCP Connections and Connect an MCP server.
PATCH /v1/mcp-connections/:id
Renames one MCP Connection. MCP Connections are Tenant configuration and do not carry Attribution.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Path | id | yes | MCP Connection ID. |
| Location | Field | Required | Description |
|---|---|---|---|
| Body | name | yes | New unique display name; at least one field is required. |
| Header | Content-Type | yes | application/json. |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
200 OK | McpConnectionResponse | Updates the definition without changing stored credentials. |
Response schema: mcpConnectionResponseSchema.
Errors
400 invalid_request; 404 not_found; duplicate names conflict. See REST errors.
cURL
curl --request PATCH "$BLAZING_AGENTS_BASE_URL/v1/mcp-connections/mcp_1234567890ABCDEF" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"Docs production"}'SDK and related guides
SDK: update. See MCP Connections and Connect an MCP server.
DELETE /v1/mcp-connections/:id
Deletes one MCP Connection. MCP Connections are Tenant configuration and do not carry Attribution.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Path | id | yes | MCP Connection ID. |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
204 No Content | Empty | Removes the definition and revokes stored OAuth credentials. |
Errors
404 not_found; an Agent reference returns exactly 409 invalid_request. See REST errors.
cURL
curl --request DELETE "$BLAZING_AGENTS_BASE_URL/v1/mcp-connections/mcp_1234567890ABCDEF" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"SDK and related guides
SDK: delete. See MCP Connections and Connect an MCP server.
POST /v1/mcp-connections/:id/test
Tests a stored MCP Connection and discovers its server and tools. MCP Connections are Tenant configuration and do not carry Attribution.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Path | id | yes | MCP Connection ID. |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
200 OK | McpConnectionTestResponse | Persists status and lastAuthErrorCode; OAuth testing may also renew a token. |
Test always returns HTTP 200 after finding the stored connection and persists both fields: success returns ok: true, sets status: "connected", and clears lastAuthErrorCode; authentication rejection returns ok: false, sets status: "needs_auth", and records its code; other live validation or connectivity failures return ok: false, set status: "error", and record their code. OAuth testing may renew stored token material before reporting the result.
Response schema: mcpConnectionTestResponseSchema.
Errors
404 not_found for a missing connection. A stored unsafe URL is impossible because create and reconnect validate before persistence; live validation and connectivity failures normally return 200 { "ok": false, "error": "…" }. See REST errors.
cURL
curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/mcp-connections/mcp_1234567890ABCDEF/test" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"SDK and related guides
SDK: test. See MCP Connections and Connect an MCP server.
POST /v1/mcp-connections/:id/connect
Starts authorization-code OAuth for a stored MCP Connection. MCP Connections are Tenant configuration and do not carry Attribution.
Request
Requires a dashboard Supabase JWT. The dashboard JWT selects the Tenant ownership boundary; the authenticated administrator and every referenced resource must belong to that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Dashboard Supabase JWT; Tenant API keys are rejected. |
| Path | id | yes | MCP Connection ID. |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
200 OK | McpConnectionOauthConnectResponse | Creates a short-lived setup continuation and returns a dashboard URL. |
Response schema: mcpConnectionOauthConnectResponseSchema.
Errors
403 invalid_request when authentication does not provide the dashboard JWT's authUserId. The current service maps a missing or foreign connection—and a connection with the wrong auth type or status—to 500 internal, not 404. See REST errors.
cURL
curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/mcp-connections/mcp_1234567890ABCDEF/connect" \
--header "Authorization: Bearer $BLAZING_AGENTS_DASHBOARD_JWT"SDK and related guides
SDK: connect. See MCP Connections and Connect an MCP server.
POST /v1/mcp-connections/:id/reconnect
Replaces the endpoint and credential configuration for a disconnected MCP Connection. MCP Connections are Tenant configuration and do not carry Attribution.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Path | id | yes | MCP Connection ID. |
| Location | Field | Required | Description |
|---|---|---|---|
| Body | authType | yes | Authentication discriminant. |
| Body | url | yes | Replacement remote URL; credential fields depend on authType. |
| Body | bearerToken | conditional | Required only for bearer. |
| Body | clientId | conditional | Required with clientSecret for client credentials; optional but paired for authorization code. |
| Body | clientSecret | conditional | Required with clientId for client credentials; optional but paired for authorization code. |
| Body | scope | no | Optional OAuth scope for either OAuth mode. |
| Header | Content-Type | yes | application/json. |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
200 OK | McpConnectionReconnectResult | Returns connected after live validation, or needs_auth for authorization-code OAuth. |
Reconnect to none, bearer, or client credentials validates before replacing the stored configuration and returns connected. Reconnect to authorization-code OAuth stores the replacement as needs_auth; use connect to continue. Live test or runtime failures may later move a stored connection from connected to needs_auth for authentication rejection or to error for other failures.
Response schema: mcpConnectionReconnectResultSchema.
Errors
400 invalid_request for an unsafe URL, invalid discriminated configuration, OAuth discovery failure, rejected credentials, or unreachable/invalid server; failed validation leaves the existing configuration unchanged. 404 not_found applies to the stored connection lookup. See REST errors.
cURL
curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/mcp-connections/mcp_1234567890ABCDEF/reconnect" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
--header "Content-Type: application/json" \
--data '{"authType":"none","url":"https://mcp.example.com/mcp"}'SDK and related guides
SDK: reconnect. See MCP Connections and Connect an MCP server.