---
title: "Test Connection"
method: POST
path: "/api/v1/mcp_servers/test_connection"
tags: ["MCP Servers"]
---

# Test Connection

`POST /api/v1/mcp_servers/test_connection`

TestConnection probes an MCP server with the
 supplied URL + transport + plaintext credentials and reports
 whether a real MCP initialize + tools/list succeeded.

## Request body

- C1ApiAiGovernanceV1MCPServerServiceTestConnectionRequest — MCPServerServiceTestConnectionRequest exercises an MCPServerExternalConfig against the upstream server and reports whether the supplied URL + transport + credentials accept a real MCP initialize + tools/list.
  - `appId` string — App ID of an existing external MCP connector. When set together with connector_id, the request runs in edit mode (see above).
  - `connectorId` string — Connector ID of an existing external MCP connector. When set together with app_id, the request runs in edit mode (see above).
  - `externalConfig` C1ApiAiGovernanceV1MCPServerExternalConfig — MCPServerExternalConfig configures an external MCP server accessed via HTTP transport. The server is routed through the MCP gateway for credential decryption. This message contains a oneof named auth_config. Only a single field of the following list may be set at a time: - none - bearerToken - oauth2 - customHeader - basicAuth
    - `basicAuth` C1ApiAiGovernanceV1MCPServerAuthBasicAuth — MCPServerAuthBasicAuth provides HTTP Basic authentication (RFC 7617). The gateway encodes `username:password` as base64 and sends it as `Authorization: Basic <encoded>` on every outbound request.
      - `password` string — Password. Sealed before storage; never returned on read. ignore_empty for the same PER_USER reason as username above.
      - `username` string — Username. Sent in plaintext over TLS; stored unsealed on the connector config (mirrors how MCPAuthOAuth2.client_id is plaintext). ignore_empty mirrors MCPServerAuthBearerToken.token — PER_USER admin submits don't carry a username; the handler enforces non-empty for SHARED.
    - `bearerToken` C1ApiAiGovernanceV1MCPServerAuthBearerToken — MCPServerAuthBearerToken provides bearer token authentication.
      - `token` string — The bearer token value.
    - `customHeader` C1ApiAiGovernanceV1MCPServerAuthCustomHeader — MCPServerAuthCustomHeader provides custom header authentication.
      - `headerName` string — HTTP header name.
      - `headerValue` string — HTTP header value.
    - `none` C1ApiAiGovernanceV1MCPServerAuthNone — MCPServerAuthNone indicates no authentication is required.
    - `oauth2` C1ApiAiGovernanceV1MCPServerAuthOAuth2 — MCPServerAuthOAuth2 provides OAuth2 client credentials or JWT Bearer authentication.
      - `authorizeUrl` string — OAuth2 authorization endpoint URL (for service and passthrough modes).
      - `clientId` string — OAuth2 client identifier. Required for CLIENT_CREDENTIALS mode; not used for JWT_BEARER mode.
      - `clientIdMode` 'MCP_SERVER_AUTH_OAUTH2_CLIENT_ID_MODE_UNSPECIFIED' | 'MCP_SERVER_AUTH_OAUTH2_CLIENT_ID_MODE_DCR' | 'MCP_SERVER_AUTH_OAUTH2_CLIENT_ID_MODE_CIMD' — How the client_id is acquired for authorization_code mode. When DCR (or CIMD), client_id / client_secret are not required on input — the gateway registers itself with the authorization server during Register and injects the result. UNSPECIFIED means manual (admin-entered client_id).
      - `clientSecret` string — OAuth2 client secret. Required for CLIENT_CREDENTIALS mode; not used for JWT_BEARER mode.
      - `codeChallengeMethodsSupported` string[], nullable — PKCE code challenge methods supported by the authorization server, as returned by DiscoverOIDCEndpoints. Optional registration-time shortcut that lets the gateway skip the per-flow xjwks.Cache lookup. Capped at 8 entries because RFC 7636 / RFC 8414 only define a tiny enumerated set ("plain", "S256") and we don't want to be a dumping ground for arbitrary strings the IdP might emit.
      - `extraAuthorizeParams` object — Static query params appended to the authorize URL on top of the standard OAuth2 fields (e.g. Notion "owner=user"). Applies to authorization_code mode only. Inherited from MCPServerCatalogAuthMode.extra_authorize_params at registration time.
      - `extraTokenParams` object — Extra body params POSTed to the token endpoint on top of the standard OAuth2 fields. Provider-specific (e.g. Auth0/Wiz "audience"). Applies to client_credentials mode only; other modes ignore it. Inherited from MCPServerCatalogAuthMode.extra_token_params at registration time; admins can add, edit, or remove entries on the edit form.
      - `issuerUrl` string — OIDC issuer URL (no trailing path). Used as the cache key for live PKCE-methods discovery via xjwks.Cache on the gateway. Populated by the Discover button or hand-entered alongside authorize_url/token_url. Required for SERVICE / PASSTHROUGH modes.
      - `jwtAudience` string — Audience claim for the JWT. When empty, token_url is used as the audience.
      - `jwtIssuer` string — The service account email / issuer claim.
      - `jwtPrivateKey` string — PEM-encoded RSA private key (plaintext in API; sealed before storage).
      - `jwtSubject` string — Optional subject for domain-wide delegation.
      - `mode` 'MCP_SERVER_AUTH_OAUTH2_MODE_UNSPECIFIED' | 'MCP_SERVER_AUTH_OAUTH2_MODE_SERVICE' | 'MCP_SERVER_AUTH_OAUTH2_MODE_PASSTHROUGH' | 'MCP_SERVER_AUTH_OAUTH2_MODE_CLIENT_CREDENTIALS' | 'MCP_SERVER_AUTH_OAUTH2_MODE_JWT_BEARER' | 'MCP_SERVER_AUTH_OAUTH2_MODE_GOOGLE_SERVICE_ACCOUNT' | 'MCP_SERVER_AUTH_OAUTH2_MODE_AUTHORIZATION_CODE' — OAuth2 mode.
      - `pkce` string — PKCE behavior for authorization_code mode: "discover" (or empty), "s256", or "disabled". Inherited from MCPServerCatalogAuthMode.pkce.
      - `scopes` string[], nullable — OAuth2 scopes to request.
      - `scopesSupported` string[], nullable — Full list of OAuth scopes the IdP advertises in its discovery doc (`scopes_supported`). Distinct from the `scopes` field above, which is the curated subset the admin wants requested on the authorize URL. Captured at registration time so the edit form can offer autocomplete suggestions on the Scopes input without forcing the admin to re-run Discover. Capped at 256 because providers like Salesforce return ~36; 256 leaves headroom without inviting abuse.
      - `tokenEndpointAuthMethod` string — RFC 7591 token_endpoint_auth_method the authorization server assigned. Read-only / ignored on write: server-set from the DCR result, never copied from the API request into the stored model. Surfaced for display only.
      - `tokenUrl` string — OAuth2 token endpoint URL. Required for all modes when creating or rotating; uses ignore_empty so partial UpdateCredentials calls that omit this path pass protovalidate. The handler enforces required-on-create.
    - `requireToolApproval` 'OPTIONAL_BOOL_UNSPECIFIED' | 'OPTIONAL_BOOL_TRUE' | 'OPTIONAL_BOOL_FALSE' — Optional per-server override for tool auto-approval. See MCPServerView.require_tool_approval for semantics.
    - `tokenSharing` 'MCP_SERVER_TOKEN_SHARING_UNSPECIFIED' | 'MCP_SERVER_TOKEN_SHARING_SHARED' | 'MCP_SERVER_TOKEN_SHARING_PER_USER' — Token sharing model. SHARED = admin authorizes once; PER_USER = each user authenticates independently. PER_USER is supported for OAuth2 authorization_code, bearer_token, custom_header, and basic_auth. Defaults to SHARED at runtime.
    - `transportType` 'MCP_SERVER_TRANSPORT_TYPE_UNSPECIFIED' | 'MCP_SERVER_TRANSPORT_TYPE_STREAMABLE_HTTP' | 'MCP_SERVER_TRANSPORT_TYPE_SSE' — Transport type for the MCP connection.
    - `url` string — The HTTP endpoint URL of the external MCP server (HTTPS required).
  - `updateMask` string, nullable

## Response `200`

Successful response

- C1ApiAiGovernanceV1MCPServerServiceTestConnectionResponse — The MCPServerServiceTestConnectionResponse message.
  - `failureReason` string — Sanitized, human-readable explanation of why the probe failed, set only when reachable=false (e.g. "MCP server unreachable or rejected the credentials (HTTP 401 Unauthorized)"). Empty when reachable=true. Never contains raw upstream response bytes.
  - `reachable` boolean — True when the MCP initialize handshake AND a tools/list call both succeeded against the upstream with the supplied credentials. False when the probe ran but the upstream was unreachable or rejected the request — see failure_reason. Malformed requests (missing/invalid config, bad permissions) are returned as a gRPC error, not reachable=false.
  - `toolCount` string, int64 — Number of tools advertised by the upstream's tools/list response. Zero when reachable=false; can also legitimately be zero when the server is reachable but exposes no tools. int64 to match MCPServerSearchWithToolCountResult.tool_count.

---

[API](https://skmtc.net/conductorone/apis/c1-api.md) · [All operations](https://skmtc.net/conductorone/apis/c1-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/conductorone/c1-api/revisions/f2cf3228f366/schema)