---
title: "Test a connection before saving it"
method: POST
path: "/client/mcp/upstreams/test"
tags: ["Tool gateway"]
---

# Test a connection before saving it

`POST /client/mcp/upstreams/test`

## Request

- Base URL: `https://api.roar-ai.com`
- URL: `https://api.roar-ai.com/client/mcp/upstreams/test`
- Auth: HTTP bearer

Connects to the address with the credential given — or, with `upstreamId` and no `auth`, that server’s saved one, and then only at the exact address it was saved for — and answers with the tools it lists. Nothing is stored. At most 10 tests a minute per organisation. Owner or admin, or a key with `mcp:write`.

## Request body

- TestMcpUpstreamRequest
  - `url` string, uri, required: The address to try. https only, no username or password in it
  - `auth` McpUpstreamAuth: `{"type":"none"}`, `{"type":"bearer","token":"…"}`, `{"type":"header","header":"X-Api-Key","value":"…"}` or `{"type":"oauth"}` (sign in after saving — nothing is pasted). Stored encrypted; never returned
    - `type` 'none' | 'bearer' | 'header' | 'oauth', required
    - `token` string: For `bearer`
    - `header` string: For `header`: a header name the connection does not itself use
    - `value` string: For `header`
  - `upstreamId` string, uuid: Test with THIS saved server’s credential when `auth` is left out. It is used only for the exact address it was saved for; to test another address, send `auth`

## Response `200`

The tools the server lists

- McpTestResult
  - `auth` McpAuthDetection, required
    - `kind` 'oauth' | 'token' | 'none' | 'unknown', required: `oauth`: it names a sign-in server; `token`: it wants a credential it does not say how to get; `none`: it answered without one
    - `signInHost` string, nullable, required: For `oauth`: where a person would sign in
  - `count` integer, required: How many tools the server lists
  - `tools` object[], required
    - `name` string, required
    - `description` string, nullable, required: Cut to 300 characters

## Other responses

- `400`: Invalid address or credential, an address that is not allowed, or a saved credential asked to go to another address
- `404`: No such tool server (`upstreamId`)
- `429`: Too many tests this minute
- `502`: The server could not be reached, refused the credential, or did not speak MCP
- `504`: The server did not answer in time

---

[API](https://skmtc.dev/roar-ai/apis/roar-ai-api.md) · [All operations](https://skmtc.dev/roar-ai/apis/roar-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roar-ai/apis/roar-ai-api/revisions/37e4d0d5a7fe?raw)