> ## Documentation Index > Fetch the complete documentation index at: https://allhandsai-chore-regenerate-agent-sdk-openapi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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). ## OpenAPI ````yaml /openapi/agent-sdk.json post /api/mcp/test openapi: 3.1.0 info: description: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent title: OpenHands Agent Server version: 1.52.0 servers: [] security: [] paths: /api/mcp/test: post: tags: - MCP summary: Test an MCP server configuration description: >- 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). operationId: test_mcp_server_api_mcp_test_post requestBody: content: application/json: schema: $ref: '#/components/schemas/MCPTestRequest' required: true responses: '200': content: application/json: schema: discriminator: mapping: 'False': '#/components/schemas/MCPTestFailure' 'True': '#/components/schemas/MCPTestSuccess' propertyName: ok oneOf: - $ref: '#/components/schemas/MCPTestSuccess' - $ref: '#/components/schemas/MCPTestFailure' title: Response Test Mcp Server Api Mcp Test Post description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error security: - APIKeyHeader: [] components: schemas: MCPTestRequest: description: Body for ``POST /api/mcp/test``. properties: name: default: test-server description: >- Name to use for the server inside the temporary MCP server map. Only affects error messages -- does not need to match any persisted setting. maxLength: 128 minLength: 1 title: Name type: string server: discriminator: mapping: http: '#/components/schemas/_RemoteMCPServerSpec' shttp: '#/components/schemas/_RemoteMCPServerSpec' sse: '#/components/schemas/_RemoteMCPServerSpec' stdio: '#/components/schemas/_StdioMCPServerSpec' streamable-http: '#/components/schemas/_RemoteMCPServerSpec' propertyName: type oneOf: - $ref: '#/components/schemas/_StdioMCPServerSpec' - $ref: '#/components/schemas/_RemoteMCPServerSpec' title: Server timeout: default: 15 description: Seconds to wait for connection + tools/list to complete. exclusiveMinimum: 0 maximum: 120 title: Timeout type: number tool_call: anyOf: - $ref: '#/components/schemas/MCPToolCallSpec' - type: 'null' description: >- Optional 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`. required: - server title: MCPTestRequest type: object MCPTestFailure: description: |- Response when the candidate server fails to connect or list tools. The endpoint returns HTTP 200 in both success and failure cases: a failure here is the *expected* outcome of validating a user-supplied config, not a server-side error. The structured shape makes it easy for the UI to render an actionable message. properties: error: description: Human-readable error message. title: Error type: string error_kind: description: Coarse error classification, useful for branching UI. enum: - timeout - connection - unknown title: Error Kind type: string ok: const: false default: false title: Ok type: boolean required: - error - error_kind title: MCPTestFailure type: object MCPTestSuccess: description: Response when the candidate server connects and lists its tools. properties: oauth_state: anyOf: - $ref: '#/components/schemas/MCPOAuthStateResponse' - type: 'null' description: >- Serialized OAuth state acquired or refreshed by the probe. Clients should persist this under the tested server's auth.state. ok: const: true default: true title: Ok type: boolean resolved_mcp_servers: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' deprecated: true description: >- Deprecated compatibility field for older clients that expected resolved MCP server metadata in test responses. title: Resolved Mcp Servers tool_result: anyOf: - $ref: '#/components/schemas/MCPToolCallResult' - type: 'null' description: Outcome of the requested `tool_call`, when one was supplied. tools: description: Names of tools advertised by the MCP server. items: type: string title: Tools type: array title: MCPTestSuccess type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object _RemoteMCPServerSpec: description: Legacy remote MCP server spec accepted by the public REST API. properties: auth: anyOf: - discriminator: mapping: api_key: '#/components/schemas/MCPApiKeyAuthCredential-Input' basic: '#/components/schemas/MCPBasicAuthCredential-Input' bearer: '#/components/schemas/MCPBearerAuthCredential-Input' header: '#/components/schemas/MCPHeaderAuthCredential-Input' none: '#/components/schemas/MCPNoneAuthCredential' oauth2: '#/components/schemas/MCPOAuthAuthCredential-Input' propertyName: strategy oneOf: - $ref: '#/components/schemas/MCPNoneAuthCredential' - $ref: '#/components/schemas/MCPApiKeyAuthCredential-Input' - $ref: '#/components/schemas/MCPBearerAuthCredential-Input' - $ref: '#/components/schemas/MCPBasicAuthCredential-Input' - $ref: '#/components/schemas/MCPHeaderAuthCredential-Input' - $ref: '#/components/schemas/MCPOAuthAuthCredential-Input' - type: 'null' title: Auth headers: additionalProperties: type: string title: Headers type: object keep_alive: anyOf: - type: boolean - type: 'null' title: Keep Alive sse_read_timeout: anyOf: - type: number - type: 'null' title: Sse Read Timeout timeout: anyOf: - type: number - type: 'null' title: Timeout type: enum: - http - shttp - streamable-http - sse title: Type type: string url: minLength: 1 title: Url type: string required: - type - url title: _RemoteMCPServerSpec type: object _StdioMCPServerSpec: description: Legacy stdio MCP server spec accepted by the public REST API. properties: args: items: type: string title: Args type: array command: description: Executable to invoke minLength: 1 title: Command type: string cwd: anyOf: - type: string - type: 'null' title: Cwd env: additionalProperties: type: string title: Env type: object type: const: stdio default: stdio title: Type type: string required: - command title: _StdioMCPServerSpec type: object MCPToolCallSpec: description: |- A single tool invocation to run as part of the connection test. Listing tools does not exercise the credentials many servers only use inside tool handlers, so callers can name one tool to invoke after the listing succeeds. Callers are responsible for choosing a read-only tool; the endpoint executes it verbatim. properties: arguments: additionalProperties: true description: Arguments passed to the tool unchanged. title: Arguments type: object name: description: Name of the tool to invoke minLength: 1 title: Name type: string required: - name title: MCPToolCallSpec type: object MCPOAuthStateResponse: properties: client_info: anyOf: - additionalProperties: true properties: client_secret: anyOf: - type: string - type: 'null' title: Client Secret title: MCPOAuthClientInfoState type: object - type: 'null' title: Client Info token_expires_at: anyOf: - type: number - type: 'null' title: Token Expires At tokens: anyOf: - additionalProperties: true properties: access_token: anyOf: - type: string - type: 'null' title: Access Token refresh_token: anyOf: - type: string - type: 'null' title: Refresh Token title: MCPOAuthTokenState type: object - type: 'null' title: Tokens title: MCPOAuthStateResponse type: object MCPToolCallResult: description: |- Verbatim outcome of the requested ``tool_call``. The endpoint stays provider-neutral: many servers report upstream failures (e.g. Slack's ``{"ok": false, "error": "invalid_auth"}``) as ordinary text content with ``isError`` unset, so interpreting the payload is the caller's job. properties: is_error: description: The MCP-level isError flag of the result. title: Is Error type: boolean text: description: Concatenated text content of the result. title: Text type: string required: - is_error - text title: MCPToolCallResult type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object MCPApiKeyAuthCredential-Input: properties: header_name: anyOf: - type: string - type: 'null' title: Header Name strategy: const: api_key title: Strategy type: string value: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Value required: - strategy title: MCPApiKeyAuthCredential type: object MCPBasicAuthCredential-Input: properties: password: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Password strategy: const: basic title: Strategy type: string username: title: Username type: string required: - strategy - username title: MCPBasicAuthCredential type: object MCPBearerAuthCredential-Input: properties: strategy: const: bearer title: Strategy type: string value: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Value required: - strategy title: MCPBearerAuthCredential type: object MCPHeaderAuthCredential-Input: properties: headers: additionalProperties: format: password type: string writeOnly: true title: Headers type: object strategy: const: header title: Strategy type: string required: - strategy title: MCPHeaderAuthCredential type: object MCPNoneAuthCredential: properties: strategy: const: none title: Strategy type: string required: - strategy title: MCPNoneAuthCredential type: object MCPOAuthAuthCredential-Input: properties: authentication: anyOf: - $ref: '#/components/schemas/MCPOAuthAuthentication-Input' - type: 'null' state: anyOf: - $ref: '#/components/schemas/MCPOAuthState-Input' - type: 'null' strategy: const: oauth2 title: Strategy type: string required: - strategy title: MCPOAuthAuthCredential type: object MCPOAuthAuthentication-Input: additionalProperties: false properties: additional_client_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Additional Client Metadata client_auth_method: anyOf: - enum: - none - client_secret_post - client_secret_basic - private_key_jwt type: string - type: 'null' title: Client Auth Method client_id: anyOf: - type: string - type: 'null' title: Client Id client_metadata_url: anyOf: - type: string - type: 'null' title: Client Metadata Url client_name: anyOf: - type: string - type: 'null' title: Client Name client_secret: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Client Secret scopes: anyOf: - type: string - items: type: string type: array - type: 'null' title: Scopes type: const: oauth title: Type type: string required: - type title: MCPOAuthAuthentication type: object MCPOAuthState-Input: properties: client_info: anyOf: - $ref: '#/components/schemas/MCPOAuthClientInfoState-Input' - type: 'null' token_expires_at: anyOf: - type: number - type: 'null' title: Token Expires At tokens: anyOf: - $ref: '#/components/schemas/MCPOAuthTokenState-Input' - type: 'null' title: MCPOAuthState type: object MCPOAuthClientInfoState-Input: additionalProperties: true properties: client_secret: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Client Secret title: MCPOAuthClientInfoState type: object MCPOAuthTokenState-Input: additionalProperties: true properties: access_token: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Access Token refresh_token: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Refresh Token title: MCPOAuthTokenState type: object securitySchemes: APIKeyHeader: in: header name: X-Session-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.