Test MCP Config

Source: test-mcp-config/ When you configure an MCP server in the OpenHands UI, there’s no feedback on whether it actually connects. A bad URL or wrong token causes the server’s tools to silently disappear from the agent’s toolset. This example uses the agent-server’s POST /api/mcp/test endpoint to validate a config end-to-end before using it.

Requires agent-server 1.29.0 / OpenHands 1.8.0 or later. Older runtimes return 404.

How It Works

POST /api/v1/sandboxes              # 1. Start a sandbox (no conversation needed)
GET  /api/v1/sandboxes?id=<id>      # 2. Poll until RUNNING
POST {agent}/api/mcp/test           # 3. Validate the MCP config
DELETE /api/v1/sandboxes/<id>       # 4. Clean up

The POST /api/mcp/test endpoint connects to a single MCP server, lists its tools, and optionally calls a specific tool to verify credentials. It returns HTTP 200 in both success and failure cases — a connection failure is an expected validation result, not a server error.

Response Format

// Success
{"ok": true, "tools": ["list_issues", "create_issue"], "tool_result": null}

// Failure
{"ok": false, "error": "Client failed to connect: connection refused", "error_kind": "connection"}

error_kind is one of: timeout, connection, or unknown. Auth failures (e.g., a 401) currently return as unknown — read error for the full message.

Usage

export OH_API_KEY="your-api-key"
pip install requests

# Validate a streamable-HTTP server with a bearer token
python test_mcp_config.py \
    --url https://mcp.example.com/mcp \
    --type shttp \
    --server-api-key "$TOKEN"

# Also invoke a specific tool to exercise the credentials
python test_mcp_config.py \
    --url https://mcp.example.com/mcp \
    --header "Authorization=Bearer $TOKEN" \
    --tool-call list_resources

# Validate a local stdio (subprocess) server
python test_mcp_config.py \
    --type stdio \
    --command "uvx mcp-server-fetch"

Supported Transport Types

Type	`--type` flag	Typical use
Streamable HTTP	`shttp`	Remote HTTP MCP servers
Server-Sent Events	`sse`	Older HTTP MCP servers
Stdio (subprocess)	`stdio`	Local CLI-based MCP servers

Multiple Configs at Once

Pass a JSON file with multiple server configurations to validate them all in one run:

python test_mcp_config.py --config servers.json

servers.json

[
  {"url": "https://linear.mcp.example.com/mcp", "type": "shttp", "api_key": "lin_xxx"},
  {"url": "https://github.mcp.example.com/mcp", "type": "shttp", "api_key": "ghp_xxx"}
]

Sandboxes

Conversations

Plugins & Skills

Hooks

How It Works

Response Format

Usage

Supported Transport Types

Multiple Configs at Once

See Also

​How It Works

​Response Format

​Usage

​Supported Transport Types

​Multiple Configs at Once

​See Also

How It Works

Response Format

Usage

Supported Transport Types

Multiple Configs at Once

See Also