To test an MCP endpoint with curl, first confirm the server uses HTTP—not stdio—then match the request to its MCP protocol version. For a server using the 2026-07-28 Streamable HTTP format, send a POST to its configured endpoint and inspect both the HTTP response and the JSON-RPC body. A successful connection alone does not prove the method or client configuration is correct.
Does the MCP server use HTTP or stdio?
MCP supports Streamable HTTP and stdio as standard transports. curl can probe an HTTP endpoint; it cannot directly test a server launched as a local subprocess that communicates through stdin and stdout. If the server is configured for stdio, check the client’s launch command and the server’s stdin/stdout protocol instead. See the MCP Streamable HTTP specification and the 2025-11-25 transport specification.
As an Amazon Associate I earn from qualifying purchases.
Confirm the endpoint and protocol generation
For Streamable HTTP, client messages use POST to one MCP endpoint. The URL path is set by the server; /mcp is only the path used in the example below. Before probing, find the actual endpoint URL, supported protocol revision, authentication requirements, and whether the server returns JSON or request-scoped server-sent events (SSE).
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Protocol generation matters. The 2026-07-28 revision carries protocol metadata with each request and removes the earlier initialize/session pattern. The 2025-11-25 transport uses an initialize handshake; a server may return an MCP-Session-Id that must accompany later requests. Consult the server’s documentation rather than assuming one payload works for every MCP endpoint.
#1 Best Overall
What curl command checks a current MCP endpoint?
For a server that implements the 2026-07-28 request format, this example asks for the available tools; it does not invoke one. Replace the URL with the endpoint configured by your server. The protocol-version header and request metadata must match.
curl -i -X POST 'http://localhost:8080/mcp'
-H 'Content-Type: application/json'
-H 'Accept: application/json, text/event-stream'
-H 'MCP-Protocol-Version: 2026-07-28'
-H 'Mcp-Method: tools/list'
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
"name": "curl-test",
"version": "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}'This request shape is adapted from the Google Cloud MCP server codelab. Its example response is HTTP 200 with a JSON-RPC result containing a tools array. That is an illustration, not a guarantee that another server uses the same path, supports tools/list, or responds with JSON rather than SSE.
Rank #2
How should you test an earlier MCP server?
Do not send the 2026-07-28 request to an older implementation and treat failure as proof that the endpoint is down. For the 2025-11-25 transport, the client first sends a version-appropriate initialize request. If the server returns an MCP-Session-Id, include it on subsequent requests; after negotiation, send the negotiated version using MCP-Protocol-Version. The exact payload and headers depend on the server’s supported revision and implementation, so use its documentation to construct the exchange rather than reusing a universal legacy example.
How to read the curl response
The -i option prints the response headers as well as the body. Read the HTTP exchange and MCP response separately: status and headers describe the transport-level result, while the JSON-RPC body indicates whether the requested method returned a result or an error. Streamable HTTP can return JSON or a request-scoped SSE response.
Rank #3
- HTTP 200 with a JSON-RPC result: The request reached a handler that returned a result. For
tools/list, inspect whether the body contains the expectedtoolsarray; an HTTP success by itself does not establish that your AI client is configured correctly. - HTTP 400: Under the current transport specification, an unsupported protocol version produces HTTP 400. Check that the version in the header and request metadata is supported and consistent.
- HTTP 404 with a JSON-RPC method-not-found error: The endpoint responded, but the method may not be implemented. By contrast, a plain 404 or HTML page can indicate an incorrect route or an intervening proxy. Check the response body and configured endpoint before deciding which layer failed.
- HTTP 401 or 403: Authentication or origin policy may be blocking the request. The specification requires a server to reject an invalid supplied
Originwith 403; do not disable security just to make a probe pass. - Connection, TLS, or timeout error: No useful MCP response was received. Check the hostname, port, path, DNS or network access, TLS trust, server process, and proxy settings. The specific cause depends on the curl error and deployment configuration.
The status-code behaviors above are described in the 2026-07-28 Streamable HTTP specification; interpret them in light of the response body and the protocol revision actually supported by the server.
Why can curl reach the endpoint while the AI client still fails?
A successful curl request only shows that this particular HTTP request received a response. The client may use a different protocol generation, handshake, endpoint, authentication setup, or transport. Capture the client and SDK version alongside the server’s protocol revision, then compare the actual request and response rather than assuming the client sends the same exchange as the probe.
The TypeScript SDK connect guide describes a legacy initialize handshake as its default connection behavior. Its protocol-version guide documents an auto negotiation mode that probes server/discover for the 2026-era protocol and falls back to initialization for a 2025-era server. A pinned protocol era does not fall back, so SDK configuration can change what the client expects.
An SSE-only server may instead use the older HTTP+SSE transport. The SDK guide recommends trying Streamable HTTP and retrying with its SSE client transport if necessary. A successful GET to an arbitrary URL is not proof of a modern Streamable HTTP endpoint: ordinary client messages in that transport are POSTs to the MCP endpoint.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Keep the endpoint secure while testing
The 2026-07-28 MCP specification states: “Servers MUST validate the Origin header on all incoming connections to prevent DNS rebinding attacks”. It also says local servers SHOULD bind only to 127.0.0.1 rather than 0.0.0.0, and SHOULD implement proper authentication. MUST and SHOULD express different levels of normative force; a local test is not a reason to expose the endpoint or bypass its protections. See the specification’s security requirements.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
