A developer reports that an agent using an MCP server to query an internal ticketing system is failing with 'connection refused' errors on every invocation, despite the MCP server process running and responding to manual HTTP requests on the expected port. The agent's MCP configuration file specifies the correct host and port. What is the most likely cause?
Select an answer to reveal the explanation.
Short Explanation
The server is up and the address is right, but 'connection refused' means the agent isn’t getting past the door. Your MCP config is probably missing or has the wrong auth credential, so check the headers before you chase the network.
Full Explanation
When an MCP server is reachable by manual HTTP request but the agent receives 'connection refused' errors, the distinction is likely in authentication. Manual requests from a developer's terminal often include pre-configured credentials, such as environment variables, stored tokens, or explicit header flags, while the agent's MCP client uses only what is specified in its configuration file. A missing or incorrect authentication credential causes the server to reject the connection before any tool invocation occurs.
The diagnostic step is to compare the headers in a successful manual request against the headers the agent's MCP client sends. The most common fix is adding the required Authorization or X-API-Key header to the MCP server entry in the agent's configuration.
The option saying the MCP server does not support the tool the agent is trying to invoke would manifest as a different error: a successful connection followed by a tool-not-found or method-not-allowed response, not 'connection refused' before a connection is established.
The option saying the agent is attempting to use a tool that is not in its allow list is an agent-side enforcement issue: the agent's own allow list would prevent it from calling the tool, but the error message would come from the agent runtime, not the MCP server, and would not appear as 'connection refused.'
The option saying the MCP server's schema has changed and is incompatible with the agent's tool definitions would result in errors at tool negotiation time after the connection is established, not at connection establishment.
Auth misconfiguration is the primary cause of MCP server 'connection refused' errors when the server itself is running correctly.