---
title: "Test an MCP server connection"
method: POST
path: "/v2/mcp-servers:test"
tags: ["MCP Gateway"]
---

# Test an MCP server connection

`POST /v2/mcp-servers:test`

Probes an upstream MCP server connection without persisting it. Returns discovered tools and connectivity status.

## Request body

- TestMcpServerRequest
  - `connection` McpConnection
    - `type` 'MCP_CONNECTION_TYPE_UNSPECIFIED' | 'MCP_CONNECTION_TYPE_HTTP' | 'MCP_CONNECTION_TYPE_SSE' | 'MCP_CONNECTION_TYPE_STDIO', required
    - `url` string, required — Upstream endpoint; must use the http or https scheme.
  - `auth` McpAuthConfig
    - `type` 'MCP_AUTH_TYPE_UNSPECIFIED' | 'MCP_AUTH_TYPE_NONE' | 'MCP_AUTH_TYPE_STATIC_HEADERS' | 'MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS' | 'MCP_AUTH_TYPE_PER_USER_OAUTH', required
    - `static_headers` McpHeaderSecret[] — Headers sent upstream on every request; at least one entry when type is STATIC_HEADERS.
      - `key` string — Header name sent to the upstream server.
      - `value` string — Header value; accepted on write and never returned.
      - `masked_value` string — Redacted preview of `value`, returned in its place.
    - `oauth` McpOAuthConfig
      - `client_id` string — OAuth client identifier presented to the upstream authorization server.
      - `client_secret` string — OAuth client secret; accepted on write and never returned.
      - `token_url` string — Token endpoint the gateway calls to mint upstream access tokens.
      - `scopes` string[] — Scopes requested when minting upstream access tokens.
      - `masked_value` string — Redacted preview of `client_secret`, returned in its place.
  - `id` string — Probe a stored server instead of sending `connection` and `auth`.
  - `discovery_variables` object — Values for the server's `template_variables`; treated as sensitive and not persisted.

## Response `200`

OK

- TestMcpServerResponse
  - `result` McpTestResult
    - `ok` boolean — Whether the probe connected and listed tools successfully.
    - `tools` McpTool[] — Tools discovered during the probe; not persisted.
      - `name` string — Bare tool name as advertised by the upstream server.
      - `description` string — Tool description advertised upstream, passed through to MCP clients.
      - `input_schema` object — JSON Schema for the tool arguments, as advertised upstream.
      - `status` string — `ACTIVE`, or `MISSING` when the last sync no longer found the tool upstream.
      - `id` string — Assigned once on first discovery and preserved across sync.
      - `title` string — Human-readable label advertised upstream, when the server sends one.
      - `annotations` McpToolAnnotations — Hints claimed by the upstream server; the gateway does not enforce them.
        - `read_only` boolean — Upstream claims the tool does not modify state.
        - `destructive` boolean — Upstream claims the tool can perform destructive updates.
        - `idempotent` boolean — Upstream claims repeated calls with the same arguments have no extra effect.
        - `open_world` boolean — Upstream claims the tool reaches systems outside its own domain.
    - `latency_ms` integer — Round trip time of the probe in milliseconds.
    - `error_message` string — Human-readable reason the probe failed.
    - `errors` string[] — Additional failure details collected during the probe.

---

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