An MCP client cannot connect

The four refusals#

The header-agreement rule is the one that surprises implementers, and the reason is worth knowing: a load balancer that routes on the header and a server that executes on the body must not be able to see two different requests. A mismatch is therefore a refusal rather than a preference for one of the two.

What the endpoint is#

POST /mcp HTTP/1.1
Host: connectbyjbrh.com
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28

{"jsonrpc":"2.0","id":1,"method":"tools/list",
 "params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}

Transport

Streamable HTTP, one endpoint, POST only.

Supported revisions

2026-07-28, and the three initialization-based revisions before it. An older client that sends initialize gets a normal result and its later requests are accepted without per-request metadata, because refusing them would cut off the connector directories that speak those revisions.

Sessions

None. Mcp-Session-Id is ignored and never minted, and Last-Event-ID is ignored because streams are not resumable. A client waiting to be given a session id waits for something that will not arrive.

Batches

Not accepted. Send one JSON-RPC message per request.

Size and rate

A body over 256 KB is refused, and the endpoint allows 120 calls per minute per client before answering 429.

Discovery

GET /.well-known/mcp.json describes the endpoint, its transport, the supported revisions and the public tool names.

Authentication, which is narrower than it looks#

The public documentation tools need no credential and touch no workspace: they read the same generated corpus the website serves. So a connection that fails while calling search_public_docs is not an authentication problem, whatever the client's error text says — there is nothing to authenticate against.

• Ten public tools are available without a key: searching and fetching documentation pages, listing and getting a capability, getting a workflow, searching the glossary, getting a technology or a protocol page, the product status, and the changelog.
• Workspace tools require an integration key and are scoped to that key's single workspace.
• Workspace tools call the existing domain services, so autonomy, approval, suppression, sales limits, metering and the audit trail all still apply to anything an agent does through them.
• There is deliberately no tool that runs a query, none that proxies an arbitrary internal route, and no write that bypasses the service owning the record.

What Connect completed#

Every one of these refusals is a complete, deliberate answer. The server validated the request, decided, and replied with a JSON-RPC error carrying a code and, where it helps, the data needed to correct the call — the list of supported revisions, for instance. Nothing was left open and no workspace was touched, which is why a refused request costs nothing and can be corrected and retried immediately.

What Connect did not complete#

It did not establish a session, because it never establishes one. It also does not negotiate downward mid-conversation: a request naming an unsupported revision is refused rather than answered under a different one. And it does not tell a browser-based client which origins are acceptable — an unrecognised origin is refused without enumerating the alternatives, since publishing that list would defeat the check.

What you can do#

1. Fetch the discovery document first.

   Result It names the endpoint, the transport, the supported revisions and the public tools, so most configuration mistakes are visible before you send a single JSON-RPC message.

2. Send tools/list as a plain POST with no Origin header.

   Result If that works, the transport and the version are fine and the problem is in whatever your client adds — an Origin, a session expectation, or a mismatched header.

3. If you get -32020, remove the headers and rely on the body.

   Result The disagreement disappears. Add the headers back one at a time to find which one your client is filling in differently.

4. If you get 429, slow down and retry.

   Result The limit is per client per minute; it is a rate refusal, not a block, and nothing needs to be reconfigured.

When to escalate#

Escalate when a correctly formed POST on a supported revision, with no Origin, is refused for a reason not in the table above — and quote the JSON-RPC error code, which is the part that identifies the check that fired. A workspace tool refusing an integration key that works elsewhere is also worth raising, since keys are scoped to one workspace and a scope mismatch reads as an authentication failure.

Questions#

Related#

• The Connect MCP server
• Authenticating to the MCP server
• MCP error shapes
• Using Connect from any MCP client
• An AI client calling a Connect MCP tool
• Interoperating over A2A
• Troubleshooting