curl --request POST \
--url https://api.example.com/api/mcp/test \
--header 'Content-Type: application/json' \
--header 'X-Session-API-Key: <api-key>' \
--data '
{
"server": {
"command": "<string>",
"args": [
"<string>"
],
"cwd": "<string>",
"env": {},
"type": "stdio"
},
"name": "test-server",
"timeout": 15,
"tool_call": {
"name": "<string>",
"arguments": {}
}
}
'import requests
url = "https://api.example.com/api/mcp/test"
payload = {
"server": {
"command": "<string>",
"args": ["<string>"],
"cwd": "<string>",
"env": {},
"type": "stdio"
},
"name": "test-server",
"timeout": 15,
"tool_call": {
"name": "<string>",
"arguments": {}
}
}
headers = {
"X-Session-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Session-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
server: {
command: '<string>',
args: ['<string>'],
cwd: '<string>',
env: {},
type: 'stdio'
},
name: 'test-server',
timeout: 15,
tool_call: {name: '<string>', arguments: {}}
})
};
fetch('https://api.example.com/api/mcp/test', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/mcp/test",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'server' => [
'command' => '<string>',
'args' => [
'<string>'
],
'cwd' => '<string>',
'env' => [
],
'type' => 'stdio'
],
'name' => 'test-server',
'timeout' => 15,
'tool_call' => [
'name' => '<string>',
'arguments' => [
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Session-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/mcp/test"
payload := strings.NewReader("{\n \"server\": {\n \"command\": \"<string>\",\n \"args\": [\n \"<string>\"\n ],\n \"cwd\": \"<string>\",\n \"env\": {},\n \"type\": \"stdio\"\n },\n \"name\": \"test-server\",\n \"timeout\": 15,\n \"tool_call\": {\n \"name\": \"<string>\",\n \"arguments\": {}\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Session-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/mcp/test")
.header("X-Session-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"server\": {\n \"command\": \"<string>\",\n \"args\": [\n \"<string>\"\n ],\n \"cwd\": \"<string>\",\n \"env\": {},\n \"type\": \"stdio\"\n },\n \"name\": \"test-server\",\n \"timeout\": 15,\n \"tool_call\": {\n \"name\": \"<string>\",\n \"arguments\": {}\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/mcp/test")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Session-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"server\": {\n \"command\": \"<string>\",\n \"args\": [\n \"<string>\"\n ],\n \"cwd\": \"<string>\",\n \"env\": {},\n \"type\": \"stdio\"\n },\n \"name\": \"test-server\",\n \"timeout\": 15,\n \"tool_call\": {\n \"name\": \"<string>\",\n \"arguments\": {}\n }\n}"
response = http.request(request)
puts response.read_body{
"oauth_state": {
"client_info": {
"client_secret": "<string>"
},
"token_expires_at": 123,
"tokens": {
"access_token": "<string>",
"refresh_token": "<string>"
}
},
"ok": true,
"resolved_mcp_servers": [
{}
],
"tool_result": {
"is_error": true,
"text": "<string>"
},
"tools": [
"<string>"
]
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"ctx": {},
"input": "<unknown>"
}
]
}Test an MCP server configuration
Attempt to connect to a candidate MCP server and list its tools, without persisting any settings. Useful for validating user input in ‘add MCP server’ flows before storing the config. For OAuth servers, any acquired state is returned as oauth_state so clients can persist it under the MCP server object’s auth.state. Optionally invokes one caller-chosen (read-only) tool via tool_call and reports its outcome in tool_result, so callers can verify credentials that are only exercised on tool invocation. Encrypted env/headers values round-tripped from settings are decrypted before the connection is attempted. Returns 200 with ok=false for connection / timeout failures (those are expected during validation, not server errors).
curl --request POST \
--url https://api.example.com/api/mcp/test \
--header 'Content-Type: application/json' \
--header 'X-Session-API-Key: <api-key>' \
--data '
{
"server": {
"command": "<string>",
"args": [
"<string>"
],
"cwd": "<string>",
"env": {},
"type": "stdio"
},
"name": "test-server",
"timeout": 15,
"tool_call": {
"name": "<string>",
"arguments": {}
}
}
'import requests
url = "https://api.example.com/api/mcp/test"
payload = {
"server": {
"command": "<string>",
"args": ["<string>"],
"cwd": "<string>",
"env": {},
"type": "stdio"
},
"name": "test-server",
"timeout": 15,
"tool_call": {
"name": "<string>",
"arguments": {}
}
}
headers = {
"X-Session-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Session-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
server: {
command: '<string>',
args: ['<string>'],
cwd: '<string>',
env: {},
type: 'stdio'
},
name: 'test-server',
timeout: 15,
tool_call: {name: '<string>', arguments: {}}
})
};
fetch('https://api.example.com/api/mcp/test', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/mcp/test",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'server' => [
'command' => '<string>',
'args' => [
'<string>'
],
'cwd' => '<string>',
'env' => [
],
'type' => 'stdio'
],
'name' => 'test-server',
'timeout' => 15,
'tool_call' => [
'name' => '<string>',
'arguments' => [
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Session-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/mcp/test"
payload := strings.NewReader("{\n \"server\": {\n \"command\": \"<string>\",\n \"args\": [\n \"<string>\"\n ],\n \"cwd\": \"<string>\",\n \"env\": {},\n \"type\": \"stdio\"\n },\n \"name\": \"test-server\",\n \"timeout\": 15,\n \"tool_call\": {\n \"name\": \"<string>\",\n \"arguments\": {}\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Session-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/mcp/test")
.header("X-Session-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"server\": {\n \"command\": \"<string>\",\n \"args\": [\n \"<string>\"\n ],\n \"cwd\": \"<string>\",\n \"env\": {},\n \"type\": \"stdio\"\n },\n \"name\": \"test-server\",\n \"timeout\": 15,\n \"tool_call\": {\n \"name\": \"<string>\",\n \"arguments\": {}\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/mcp/test")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Session-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"server\": {\n \"command\": \"<string>\",\n \"args\": [\n \"<string>\"\n ],\n \"cwd\": \"<string>\",\n \"env\": {},\n \"type\": \"stdio\"\n },\n \"name\": \"test-server\",\n \"timeout\": 15,\n \"tool_call\": {\n \"name\": \"<string>\",\n \"arguments\": {}\n }\n}"
response = http.request(request)
puts response.read_body{
"oauth_state": {
"client_info": {
"client_secret": "<string>"
},
"token_expires_at": 123,
"tokens": {
"access_token": "<string>",
"refresh_token": "<string>"
}
},
"ok": true,
"resolved_mcp_servers": [
{}
],
"tool_result": {
"is_error": true,
"text": "<string>"
},
"tools": [
"<string>"
]
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"ctx": {},
"input": "<unknown>"
}
]
}Authorizations
Body
Body for POST /api/mcp/test.
Legacy stdio MCP server spec accepted by the public REST API.
- _StdioMCPServerSpec
- _RemoteMCPServerSpec
Show child attributes
Show child attributes
Name to use for the server inside the temporary MCP server map. Only affects error messages -- does not need to match any persisted setting.
1 - 128Seconds to wait for connection + tools/list to complete.
x <= 120Optional read-only tool to invoke after listing succeeds, so callers can verify credentials the server only exercises on tool invocation. Its outcome is reported verbatim in tool_result without affecting ok.
Show child attributes
Show child attributes
Response
Successful Response
- MCPTestSuccess
- MCPTestFailure
Response when the candidate server connects and lists its tools.
Serialized OAuth state acquired or refreshed by the probe. Clients should persist this under the tested server's auth.state.
Show child attributes
Show child attributes
Deprecated compatibility field for older clients that expected resolved MCP server metadata in test responses.
Outcome of the requested tool_call, when one was supplied.
Show child attributes
Show child attributes
Names of tools advertised by the MCP server.
Was this page helpful?

