---
title: "Check Workspace Mcp Server Connection"
method: POST
path: "/api/v1/workspaces/{workspace_id}/mcp-servers/check"
tags: ["mcp-servers"]
---

# Check Workspace Mcp Server Connection

`POST /api/v1/workspaces/{workspace_id}/mcp-servers/check`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in header `Otari-Key`
  - API key in header `x-api-key`

Check connection details without storing them. Organization owners/admins or this workspace's owners/admins.

What a form's Test button calls before it saves. Answers with what a stored
server's `health` would say, and records nothing. Pass `server_id` and omit
`authorization_token` to test with that server's stored token. The URL is
checked for SSRF safety first, with the same 400 a create gets.

## Path parameters

- `workspace_id` string, uuid, required

## Request body

- WorkspaceMcpServerCheckRequest: Connection details to check without storing them, for a form to test before it saves. ``server_id`` names a stored server whose token stands in when ``authorization_token`` is omitted, so an edit form can test a new URL with a token it was never shown. ``""`` checks with no token at all.
  - `allowed_tools` string[], nullable: The allow-list to report the catalog against
  - `authorization_token` string, nullable: Bearer token; omit to use the stored server's, if any
  - `server_id` string, uuid, nullable: A stored server whose token to use
  - `url` string, required: Streamable HTTP MCP endpoint

## Response `200`

Successful Response

- WorkspaceMcpServerHealth: The last connection check: whether the gateway reached the server, and what it found. Describes the server as the gateway saw it at ``checked_at``, not now: a server that answered then can be down since, and the request path checks nothing in advance on the strength of this.
  - `checked_at` string, required
  - `error` 'unsafe_url' | 'credentials_unavailable' | 'unreachable' | 'tls_failed' | 'timeout' | 'redirected' | 'unauthorized' | 'forbidden' | 'not_found' | 'server_error' | 'http_error' | 'not_mcp' | 'limits_exceeded' | 'connection_failed': Why a stored server failed its connection check. Stored on the server's row and shown to whoever manages it, so each value names a cause an operator can act on, and none carries anything the remote server said. The first two are decided before any connection is opened.
  - `http_status` integer, nullable: The HTTP status the server refused with, if any
  - `missing_allowed_tools` string[]: Allow-listed names the server did not offer
  - `status` 'healthy' | 'failing', required
  - `tool_count` integer, nullable: Live tools the allow-list admits; null when the check failed
  - `tools` string[]: Every tool name the server offers, allowed or not, up to 200; empty on a failure

## Other responses

- `400`: The URL failed the SSRF or TLS check; nothing was sent to it.
- `422`: Validation Error
- `429`: Every check slot on this gateway was busy. Try again shortly.

## Changes

- **2026-10-20** `c221df17a307`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mozilla-ai/apis/otari/changes/api/v1/workspaces/:workspace_id/mcp-servers/check/post.md)

---

[API](https://skmtc.dev/mozilla-ai/apis/otari.md) - [All operations](https://skmtc.dev/mozilla-ai/apis/otari/llms.txt) - [OpenAPI document](https://skmtc.dev/mozilla-ai/apis/otari/revisions/42276d3c251d?raw)