Skip to main content

Test a custom MCP server connection

POST 
/api/v1/mcp-servers/test-connection

Reads a stored configuration snapshot, performs the MCP handshake/tool listing and returns the observed count and latency. A concurrent update can change the record after that read. This operation reads the stored definition directly, making it useful after a configuration change.

Check success is true; a connection failure can return HTTP 200 with success false or omitted and an error. Inspect the error and repair the endpoint, authentication or network access before retrying. Authentication, validation, rate limiting and infrastructure failures can also return non-success HTTP responses.

Tests are limited to 10 per minute per project; destination restrictions apply when connecting. Rate limiting does not replace network isolation or authorization. A successful test is a point-in-time connection check, not a guarantee that every advertised tool is safe or available.

The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.

Use this in a guide: Answer questions about a website using your own Firecrawl account

Request​

Responses​

The test ran; read success for the outcome

Use the unprefixed serverId of a custom server registered in your project.​

Section ID: DOC-IN-tools-connections-servers-api-testCustomMcpServerConnection#example-mcp-servers-testCustomMcpServerConnection-request

Request example

{
  "serverId": "product-tools"
}

Guide request for 3. Check the saved connection and choose its tools. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-IN-tools-connections-servers-api-testCustomMcpServerConnection#example-cookbook-integrations-tools-connections-custom-mcp-servers-03-request

Request example

{
  "serverId": "firecrawl"
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.​

Section ID: DOC-IN-tools-connections-servers-api-testCustomMcpServerConnection#example-mcp-servers-testCustomMcpServerConnection-response

Response example

{
  "success": true,
  "toolCount": 1,
  "latencyMs": "1",
  "error": "example"
}

Illustrative response for 3. Check the saved connection and choose its tools. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-IN-tools-connections-servers-api-testCustomMcpServerConnection#example-cookbook-integrations-tools-connections-custom-mcp-servers-json-01-response

Response example

{
  "success": true,
  "toolCount": 26,
  "latencyMs": "556"
}

Document ID: DOC-IN-tools-connections-servers-api-testCustomMcpServerConnection. Section identities and revisions.

SectionStable reference
Test a custom MCP server connectionDOC-IN-tools-connections-servers-api-testCustomMcpServerConnection#overview
RequestDOC-IN-tools-connections-servers-api-testCustomMcpServerConnection#request
ResponsesDOC-IN-tools-connections-servers-api-testCustomMcpServerConnection#responses