An MCP server won't connect or its tools aren't called

SentientOne calls MCP servers from the cloud over HTTP, one POST per JSON-RPC call (initialize, then tools/list and tools/call). Most connection problems come from a server that isn't reachable from the internet, a transport that isn't supported, or missing credentials.

Check these in order

1. 1

   It's not a stdio server

   Servers that run as a local process (stdio) can't be called from the cloud. Run the server behind an HTTP endpoint, or use one that offers streamable HTTP.

2. 2

   It answers HTTP POST

   The server must accept JSON-RPC over POST and answer in JSON or an event-stream body. The older SSE transport (a GET stream plus a separate POST address) isn't supported. If your URL has no path, discovery also tries it with /mcp added.

3. 3

   It's on a public address

   Private, loopback, link-local and other non-public addresses are refused, and so is localhost. Redirects aren't followed. Use the server's public URL. See MCP network rules.

4. 4

   The auth matches

   Choose the auth the server expects: none, a bearer token (Authorization: Bearer …), an API key in a header you name, or basic. Add any other headers it needs. See MCP authentication.

5. 5

   It answers within the time limits

   Discovery waits 10 seconds per call. During a chat, each tool call has 10 seconds. Slow tools fail and the agent carries on without them.

6. 6

   The tool list is fresh

   Tools are discovered when you add or test the server, and saved with the agent, so chats never wait on discovery. After adding tools to your server, run discovery again on the agent's Tools tab.

7. 7

   The model knows when to use it

   The model decides from the tool's name, description and input schema. Give tools clear descriptions, and tell the agent in its prompt when to use them.

More questions