PARAS MADAN
All writing

Latest in AI

How to check MCP tool names after an OpenHands SDK restart

OpenHands SDK 1.63.1 fixes MCP tool names changing after resume. Test both startup and runtime tools, and check older saved conversations separately.

An MCP server can still be in your OpenHands conversation configuration when the agent says its tool doesn't exist. Check the name in the error against the list of available tools. If the only difference is a server prefix, the connection may be fine and the tool may have been registered under a different name after the conversation reopened.

OpenHands included a fix in Software Agent SDK v1.63.1, released November 20. If you add MCP servers to conversations that users can resume, check both the tool you added and any tools that were already there.

Why the name changed

In the original issue, a local echo tool was advertised as qa-rs_qa_echo when the server was added mid-conversation. After restarting, the agent saw qa_echo instead. Its next call used the name from the previous turn and failed with a tool-not-found error. The MCP server hadn't disappeared from the configuration.

It could happen in reverse as well. With one server configured at startup and another added later, reopening could add a prefix to the original server's previously bare tool name. That's why checking only whether the new tool is still listed can miss half the problem.

What v1.63.1 keeps stable

The merged fix stores the names of servers added after a conversation starts in a state field called runtime_mcp_servers. Those servers retain their prefixes on resume. Startup servers are counted separately for naming, so a lone startup server keeps its bare tool name even after another server is added at runtime.

A server added to a brand-new conversation before the first message still gets startup naming. For example, if it's the only server, seeing a bare tool name is expected. The fix covers servers explicitly added to a conversation through LocalConversation.add_mcp_servers or the agent-server MCP endpoint. The pull request notes that it doesn't address the equivalent naming case for servers introduced by a plugin loaded at runtime.

Run a restart check with two small fixtures

Use a disposable conversation with a local MCP server called fixture. Give it one tool, lookup, that returns a fixed value from an in-memory test record. Keep production connectors, credentials and customer data out of the fixture.

  1. Start the conversation and let its first turn finish. Then add the fixture server and check that the agent is offered fixture_lookup. Make one read-only call and record the name and expected result.
  2. Reopen that same persisted conversation and repeat the lookup. For the Python SDK, the persistence guide shows how to reopen using the same conversation_id and persistence_dir. If you also ship the agent-server path, run the check after restarting your isolated test instance.
  3. Repeat in a new conversation with one server configured at startup, exposing a separate tool called status. Add fixture after the first turn. Both status and fixture_lookup should retain their names and return their fixture values after resume.

Compare the tool names presented to the model and the actual tool result, not just the agent's final text. The model can sometimes answer using a value already in the conversation, which doesn't prove it could call the tool again.

Treat existing conversations separately

Older saved conversations don't contain the new runtime-server list. They load with an empty list, so upgrading alone won't restore a prefix that's already been lost. Test a fresh conversation first, then check an older one separately if your app needs to support it.

If a legacy session still points to an obsolete tool name, leave the stored history intact. If work needs to continue, start a fresh conversation with the intended configuration and carry over a short task summary rather than editing saved state or replaying previous calls. If the name is stable but the lookup still fails, check whether the server started and whether the tool is available under the current configuration. That's a different failure from a name changing on resume.

I'm Paras Madan. I help AI teams turn releases like this into technical guides and product stories that show developers what changed and what to test. Book a 30-minute call.