Atlas connects to your MCP server and then reports status failed with the error "Failed to get tools" because storeClient calls McpCatalog.defs to page the server's tools/list, and that listing either threw or returned nothing usable while the server advertised a tool capability. Fix it by confirming the server implements tools/list and advertises the tools capability in its initialize response, watching for pagination bugs, raising the server `timeout`, and reconnecting from the MCP dialog.
Why does Atlas say Failed to get tools after the MCP server connects
Atlas says "Failed to get tools" because storeClient runs McpCatalog.defs immediately after a successful connect, and McpCatalog.defs pages the server's tools/list. When that listing throws, or when the server advertises a tool capability and returns 0 usable tools, storeClient fails and the status becomes failed.
The sequence is what makes this Atlas error confusing. The connection genuinely succeeded. The transport is fine, the URL or command is fine, and no authentication is missing. The failure is one step later, in the tool listing. Atlas connects to Model Context Protocol servers and exposes their tools to the agent, and a server with no usable tools has nothing to expose, so Atlas treats it as failed rather than storing a connected client with an empty tool set. Debug the server's tools/list response, not its transport.
How to fix Failed to get tools in Atlas
Fix the Atlas "Failed to get tools" error in 4 steps: confirm the server implements tools/list and advertises the tools capability in its initialize response, watch for pagination bugs in the listing, raise the server `timeout` if the round trip is slow, then reconnect from the MCP dialog.
Start at the initialize response. A server that advertises a tool capability is promising Atlas that tools/list will work, and Atlas holds it to that promise. A server that advertises tools but does not actually implement tools/list, or implements it and returns nothing usable, will fail in storeClient every time. Check the capability declaration and the tools/list handler together. If both look correct, move to pagination, then to timing. Reconnecting the server from the Atlas MCP dialog after each change re-runs storeClient and gives you a clean read on whether the change helped.
How MCP tools/list pagination fails in Atlas
MCP.catalog in Atlas has 2 pagination guards: it throws on a duplicate nextCursor, and it throws again after MAX_LIST_PAGES pages. Both exist to stop a buggy MCP server from paging forever, and both surface to you as the same "Failed to get tools" error with the server stored at status failed.
A duplicate nextCursor means the MCP server handed Atlas the same cursor twice, which is the classic infinite-loop bug in a paginated tools/list implementation: the server never advances its cursor and would keep returning page one indefinitely. MCP.catalog detects the repeat and throws. The MAX_LIST_PAGES guard catches the slower version of the same bug, where cursors keep changing but the listing never terminates. If your MCP server paginates its tool list at all, test it against these two conditions directly. The fix belongs in the server's cursor logic, not in Atlas config.
When to raise the MCP server timeout in Atlas
Raise the `timeout` on an Atlas MCP server entry in 1 case: the tools/list round trip itself is slow. A server that connects quickly but takes a long time to enumerate its tools can blow the timeout inside McpCatalog.defs, and storeClient then fails with "Failed to get tools".
Timing is a real cause here, distinct from a broken listing. A server that queries a database, hits a remote API, or builds its tool definitions dynamically at list time can be perfectly correct and still be too slow. The tell is a listing that eventually succeeds when you call it by hand but fails under Atlas. Set `timeout` on that server entry and reconnect from the MCP dialog. Be honest about the tradeoff: a large timeout means a genuinely broken server also takes longer to be reported as failed, so raise it deliberately rather than as a first guess.
How to verify the MCP tool list works in Atlas
Verify the fix in Atlas with 1 action: reconnect the server from the MCP dialog and re-check the status. A server that reaches connected has passed storeClient, meaning McpCatalog.defs successfully paged tools/list, and the server's tools will now appear in the tool list offered to the agent.
Reconnecting from the Atlas MCP dialog re-runs the exact path that failed, which makes it the right verification step. Status connected plus tools visible in the tool list is the only proof that matters. If the status still reads failed with "Failed to get tools", the listing is still failing, and the next place to look is the server's own logs during the tools/list call. Once the tools do appear, every call the agent makes to them is permission-gated against allow, ask, and deny rules before it runs, so a newly connected server does not immediately get free rein.
How to fix it
- 01Confirm the server actually implements tools/list and advertises the tools capability in its initialize response.
- 02Watch for pagination bugs: MCP.catalog throws on a duplicate nextCursor and after MAX_LIST_PAGES pages.
- 03Raise the server `timeout` if the tools/list round trip is slow.
- 04Reconnect the server from the MCP dialog and re-check the status.
Frequently asked questions
- What does "Failed to get tools" mean in Atlas?
- It means the MCP server connected, but McpCatalog.defs could not page its tools/list. The listing either threw, or the server advertised a tool capability and returned nothing usable, so storeClient failed and the status became failed.
- My MCP server connects in Atlas but has no tools, why?
- Atlas stores a server as failed rather than connected when the tool listing produces nothing usable. Confirm the server actually implements tools/list and advertises the tools capability in its initialize response.
- Why does Atlas throw on a duplicate nextCursor?
- MCP.catalog throws on a duplicate nextCursor because a repeated cursor means the MCP server is not advancing its pagination and would page forever. Atlas also throws after MAX_LIST_PAGES pages for the same reason.
- How do I fix MCP tools/list pagination for Atlas?
- Fix the cursor logic in the MCP server itself. Each page must return a new nextCursor and the listing must terminate, otherwise MCP.catalog throws on the duplicate cursor or after MAX_LIST_PAGES pages.
- Can a slow MCP server cause Failed to get tools in Atlas?
- Yes. If the tools/list round trip is slow, McpCatalog.defs can time out. Raise the `timeout` on that server entry in your Atlas config and reconnect the server from the MCP dialog.
- How do I reconnect an MCP server in Atlas to retest the tool list?
- Reconnect the server from the Atlas MCP dialog and re-check the status. That re-runs storeClient and McpCatalog.defs, giving a clean read on whether your change fixed the listing.
- Is "Failed to get tools" a connection problem in Atlas?
- No. The transport connected successfully. The failure happens one step later, when Atlas calls McpCatalog.defs to page tools/list. Debug the server's tool listing, not its url or command.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas vs Kiro in 2026: Terminal Agent Compared to AWS's Spec-Driven IDE and CLI
Atlas vs Kiro in 2026. Kiro writes EARS-notation specs before code and charges credits; Atlas is a free, open source terminal agent with diff-before-write review.
Atlas for Zig: A Terminal-Native AI Coding Agent for build.zig Projects in 2026
Atlas is a terminal-native AI coding agent for Zig in 2026. It reads build.zig and comptime blocks, tracks your allocators, runs zig build test behind a prompt, and runs zig fmt.
Review a Pull Request with Atlas (2026 Workflow)
How to review a pull request with Atlas in 2026: bash produces the raw patch, read pulls whole files, the lsp tool's findReferences checks callers the diff never shows.
Plan a Multi-File Change Before Editing with Atlas in 2026
How to plan a multi-file change with Atlas in 2026: the plan agent denies all edit tools, you research with codebase_search and lsp, then plan_exit hands off.
Atlas with GLM-4.5-Flash: The Free Reasoning Slot in 2026
GLM-4.5-Flash is listed at $0.00 per Mtok input and output on Z.ai, with the full 128K tokens (131,072) context. Free background traffic for Atlas, rate limited.
Atlas vs. Goose: Choosing Your AI Coding Agent in 2026
Compare Atlas and Goose for 2026. Atlas offers terminal-native TUI and code-specialized features. Goose provides shareable Recipes and 70+ MCP extensions for general agentic workflows.
Atlas for C# in 2026
Atlas is a terminal-native AI coding agent for C# and the .NET SDK in 2026. Run it in a solution with a .csproj or .sln and approve every diff before dotnet build.
Atlas with GPT-5 Chat: The Only Chat Snapshot That Keeps 400K in 2026
GPT-5 Chat in Atlas: gpt-5-chat-latest is the one chat-latest snapshot that retains a full 400K context and 128K output, at $1.25 per Mtok input.