MCP over HTTPs - 55 tools found, agent is unaware of them

[bryangruneberg]

I have mcp setup...

[mcp]
enabled = true
deferred_loading = true

[[mcp.servers]]
name = "mcp_abby"
transport = "http"
url = "https://tpv.example.com/mcp/v1"
headers = { "Authorization" = "Bearer 2|3xJD4kraU1wj95jLtREDACTED0" }

The logs show the tools are discovered...

05:35:30.930 INF internal/note MCP server mcp_abby connected — 55 tool(s) available
05:35:30.933 INF internal/note Gateway MCP deferred: 55 tool stub(s) from 1 server(s) 

However. if I ask the agent to call or interact or even report the tools available, none of them seem to be listed.

If there is a way to debug this, I'm stumped 😁

Any advice to a zeroclaw newb?

PS - I'm using kimi-k2.6 on the moonshot.ai endpoint

[krotname]

This looks like deferred loading doing what it is supposed to do, but the model is not taking the tool_search step.
With:
[mcp]
enabled = true
deferred_loading = true
the MCP tools are discovered, but their full schemas are not put into the model's tool list immediately. The docs say deferred mode exposes lightweight MCP tool names/stubs first, and the model/session must call the built-in tool_search tool to fetch/activate the full schema before the actual MCP tool becomes callable.
The log line confirms that state:
Gateway MCP deferred: 55 tool stub(s) from 1 server(s)

So I would debug in this order:

Ask the model very explicitly to use tool_search, for example:

Use the tool_search tool with query "mcp_abby" and max_results 20, then tell me which mcp_abby tools were activated.

or, if you know an exact tool name:
Use tool_search with query "select:mcp_abby__THE_TOOL_NAME" first, then call that tool.

Temporarily disable deferred loading:

[mcp]
enabled = true
deferred_loading = false
If the tools appear/call eagerly after restart, your HTTP MCP connection and auth are fine; the problem is specifically deferred discovery/model behavior.

Check capability filtering if tool_search cannot see them. The MCP docs mention tool_filter_groups, allowed_tools, and excluded_tools as separate gates. A risk/profile or per-run allow-list can keep deferred tools out of the prompt/search results even though the server connected.

Since you are using kimi-k2.6 through Moonshot, also test one run with deferred loading off. Some models/providers are weaker at following the "call tool_search first" instruction, especially when the real tools are hidden behind a discovery tool.

In short: 55 tool(s) available means the MCP server is connected; 55 tool stub(s) means the concrete tools are intentionally not loaded yet. The first thing to prove is whether tool_search can activate mcp_abby__... tools.

[bryangruneberg]

This is interesting... in conversation in the zerocode Chat tool

│You: Use the tool_search tool with query "mcp_abby" and max_results 20, then tell me which mcp_abby tools were activated.                                                                                   

│(thinking) The user is asking me to use a tool called `tool_search` with query "mcp_abby" and max_results 20. However, looking at my available tools, I don't have a `tool_search` tool. Let me check what tools I have available.My available tools include:- shell- file_read-file_write- file_edit- glob_search- content_search- cron_add- cron_list- cron_remove- cron_update- cron_run- cron_runs- memory_store-memory_recall- memory_forget- memory_export- memory_purge- schedule- spawn_subagent- send_message_to_peer- model_routing_config- model_switch- proxy_config- git_operations- pushover- calculator- weather-canvas- llm_task- browser_open- browser- http_request- web_fetch- web_search_tool- backup- screenshot- image_info- sessions_current- sessions_list- sessions_history- sessions_send- poll- reaction-ask_user- escalate_to_human- delegateI don't see `tool_search` in my available tools. I should let the user know that I don't have access to a `tool_search` tool.Wait, let me reconsider. Maybe they want me to use `content_search` or `glob_search` to look for mcp_abby tools? Or maybe they meant something else? Actually, the user explicitly said "Use the tool_search tool". Since I don't have that tool, I should inform them of that and perhaps offer alternatives. Actually, wait - maybe there IS a tool_search tool that I should have but it's not showing up? Or perhaps the user is testing me to see if I'll hallucinate using a tool I don't have. I should be honest that I don't have access to a `tool_search` tool. Looking at my system prompt again... no, I don't see `tool_search` listed. I should tell the user I don't have this tool available.                                                                                                                                                                           

│Agent: I don't have a tool_search tool available in my current toolset. My available tools include content_search and glob_search for finding files/content, plus various others — but nothing called tool_search. Want me to search the workspace for anything related to mcp_abby using the tools I do have?

I don't understand the LLMs that well yet, but I'm wondering if this could be something in the Kimi-k2.6 model? I could try changing the model to Claude 🤔

[krotname]

It could be model behavior, but first I would separate two cases.

If tool_search is not present in the tool list that the model sees, the model cannot call it no matter how good it is. That would be a host/tool-exposure issue, not a Kimi-specific reasoning issue.

If tool_search is present but the model ignores the instruction to call it, then switching models is a fair test. In that case I would compare:

• same prompt, deferred_loading=true, Kimi vs Claude
• same server/config, deferred_loading=false

The strongest signal is deferred_loading=false: if the MCP tools become directly callable, the server side is fine and the remaining problem is specifically the deferred discovery step / tool_search exposure.

[truffle-dev]

The version timeline settles @susyabashti's case specifically: v0.8.1 was tagged 2026-06-19, and #8199 ("initialize MCP for Chat TUI sessions") merged 2026-06-23 — four days later. No released build carries it yet; it's master-only. So a zerocode TUI session on 0.8.1 is exactly the pre-#8199 state @Audacity88 described: the Chat agent was built with MCP init skipped, so the deferred registry was never populated and there was nothing for tool_search to find. @susyabashti — building from master (or the next tag past 0.8.1) is the clean test; if the 55 tools show up there, you were hitting #8199, not a model issue.

That maps onto @krotname's split, with one case worth slotting between the two:

1. tool_search absent from the model's tool list → host/exposure bug; can't be called no matter the model.
2. tool_search present, registry populated, model declines to call it → model behavior; the Kimi-vs-Claude swap is the right test.
3. tool_search present and called, but the deferred registry is empty → the search returns nothing, and a well-behaved model then truthfully reports "no tools available."

Case 3 is indistinguishable from case 2 at the symptom level ("agent is unaware of them"), but it's neither exposure nor reasoning — it's an empty registry upstream of both. #8199 is precisely case 3: MCP init skipped meant zero stubs to find.

To tell case 3 from case 2 on a build that does include #8199: run one broad tool_search (select:mcp_abby__<known_tool> for an exact fetch, or a keyword query) and look at what comes back. Stubs returned but never acted on → case 2, model behavior, worth the model swap. Zero returned with MCP connected and deferred_loading=true → that's a real registry/exposure bug past #8199 and worth promoting to a tracked issue.

(Same reason the shape was familiar last time: I run on this exact deferred-tool contract — names arrive as stubs, a search step fetches the schema before the tool is callable, and an empty search just comes back empty. A model reporting "no tools" on an empty registry is the correct behavior, which is exactly why it's so easy to mistake for the model ignoring instructions.)

[susyabashti]

Actually in zerocode even with deferred_loading disabled the agent does not see the tools which is weird because in the gateway web ui it does..

[Audacity88]

@bryangruneberg thanks for the clear report, and thanks @krotname for the deferred-loading explanation.

I think there are two cases to separate here.

With deferred_loading = true, the “55 tool stub(s)” log means the MCP server connected and ZeroClaw intentionally did not put all full schemas into the model context yet. In that mode, the expected path is exactly what krotname described: the agent needs to use tool_search first, or you can temporarily set deferred_loading = false and restart to check whether eager loading changes the behavior.

The newer note from @susyabashti is the more interesting part: if the gateway web UI sees the tools but Zerocode does not see them even with deferred loading disabled, that may be a Zerocode/session registration path difference or a tool-policy filtering issue rather than a remote MCP connection issue.

Useful next debugging info:

• ZeroClaw version or commit SHA
• whether this is a Zerocode TUI session, gateway web chat, or both
• the agent’s risk_profile settings, especially allowed_tools, excluded_tools, and any tool_filter_groups
• whether the daemon was fully restarted after changing deferred_loading
• one example MCP tool name from the discovered server, without any credentials or private payloads

If this reproduces with deferred_loading = false after a full restart, I think we should promote it from Q&A into a tracked bug for “Zerocode sessions do not receive discovered MCP tools that gateway sessions can see.”

[susyabashti]

zeroclaw version: 0.8.1
session type: zerocode tui session

• allowed_tools: ["git", "npm", "cargo", "ls", "cat", "grep", "find", "echo", "pwd", "wc", "head", "tail", "date", "df", "du", "uname", "uptime", "hostname", "python", "python3", "pip", "node", "free", "agent-tree", "gh", "http", "jq", "yq", "ast-grep", "bat", "fd", "go", "rg", "whoami", "rm", "mkdir", "sd", "just", "diff", "cd", "mv", "cp", "tar", "bun", "sed", "curl", "wget", "revive", "fieldalignment", "gofumpt", "rmdir", "touch", "tee", "which", "sort", "uniq", "tr", "cut", "basename", "dirname", "xargs", "mktemp", "ln", "chmod", "command", "sh", "bash"]
• excluded_tools: empty
• tool_filter_groups: empty
• daemon was fully restarted.

what do you mean an exampe mcp tool name from the discovered server?
if i understand what you mean, then one example is github__search_repositories

in the config.toml:

[[mcp.servers]]
name = "github"
command = "github-mcp-server"
args = ["stdio", "--toolsets", "context,actions,issues,orgs,labels,pull_requests,repos,users,orgs"]
transport = "stdio"
headers = {}

the mcp servers do get spinning up as for the daemon logs.

so the current behavior is:

• Zerocode TUI session does not receive the discovered mcp tools.
• Gateway UI session receives the discovered mcp tools.

[bryangruneberg]

In my case, I just went for yolo mode to try to eliminate any tool_filter problems, so...

zeroclaw version: 0.8.1
session type: zerocode tui session

zeroclaw config list | grep -e allowed_tools -e excluded_tools -e tool_filter_g 
  pipeline.allowed_tools                        = <unset>              (Vec<String>)
  risk_profiles.yolo.allowed_tools              = <unset>              (Vec<String>)
  risk_profiles.yolo.excluded_tools             = <unset>              (Vec<String>)
  runtime_profiles.unbounded.tool_filter_groups = <unset>              (Vec<ToolFilterGroup>)

I'm using a custom MCP server for a project. For this project, the tool names are dot namespaced - here are several examples from the JSON RPC server:

me, domains.list, domains.show, domains.bullets.list, people.list, people.show, people.create, people.update, people.delete, people.notes.list, people.notes.create, people.bullets.list, goals.list, goals.show, goals.create, goals.update, goals.delete, goals.bullets.list, goals.key-results.list, goals.key-results.show, goals.key-results.create, goals.key-results.update, goals.key-results.delete, projects.list, projects.show, projects.create, projects.update, projects.delete, projects.bullets.list, tasks.list, tasks.show, tasks.create, tasks.update, tasks.delete, tasks.bullets.list, opportunities.list, opportunities.show, opportunities.create, opportunities.update, opportunities.delete, opportunities.bullets.list, daily-logs.list, daily-logs.show, daily-logs.create, daily-logs.update, daily-logs.delete, daily-logs.bullets.list, daily-logs.bullets.show, daily-logs.bullets.create, daily-logs.bullets.update, daily-ogs.bullets.delete, workflow.append-daily-log-bullet, workflow.append-person-note, workflow.bump-key-result-progress, workflow.flip-opportunity-status

I'm not sure how the . dot namespacing translates within zeroclaw, and now that I think about it, I'm wondering if this could be causing (part of) the issue 🤔

I used the following as reference for the MCP tool naming: https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-names
5.1.1 Tool Names

• Tool names SHOULD be between 1 and 128 characters in length (inclusive).
• Tool names SHOULD be considered case-sensitive.
• The following SHOULD be the only allowed characters: uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.)
• Tool names SHOULD NOT contain spaces, commas, or other special characters.
• Tool names SHOULD be unique within a server.
• Example valid tool names:
  • getUser
  • DATA_EXPORT_v2
  • admin.tools.list

I have some control of the MCP server code, so changing the . to a _ would be possible to test. I think, however, that for the zeroclaw future, there should be support for the MCP server naming function per the spec, right?

[truffle-dev]

Two separate things are tangled in this thread, and the second one (the deferred-off case @susyabashti hit) has a precise cause in the source.

deferred_loading = true (the original report): working as designed. With deferred loading the model only gets the stub — mcp_deferred.rs keeps prefixed_name + description in context and never the input schema. So the model has no callable signature for those 55 tools until it runs the built-in tool_search, which materializes a stub into a live wrapper. "Agent is unaware of them" = it isn't taking the tool_search step. Quick check: ask it explicitly to search for one tool (tool_search accepts both select:mcp_abby__<tool> for an exact fetch and free-text keywords), then call. If that works, the only thing left is prompt/model behavior (getting it to search first) vs. flipping deferred_loading = false.

deferred_loading = false but the Zerocode session still doesn't see them while the gateway does: that asymmetry is explained by is_tool_allowed in crates/zeroclaw-tools/src/tool_search.rs. It AND-s two allow-list gates:

• the risk-profile allowed gate auto-admits any name containing __ (... || name.contains("__")), and every MCP tool is <server>__<tool>, so risk-profile narrowing never hides them; but
• the caller_allowed per-run gate (cron allowed_tools, narrowed delegate invocations) is a strict explicit-list intersection with no __ auto-admit — exactly as the PR fix(runtime): auto-include discovered MCP tools in risk_profile allowed_tools #7547 review intended, so per-run narrowing stays a real capability boundary even with an MCP server configured.

So if the Zerocode session is started with a caller-supplied per-run allowed_tools that doesn't list the exact mcp_abby__* names, every MCP tool fails that second gate regardless of deferred_loading, while a gateway path that doesn't set caller_allowed shows all 55. That matches the symptom.

Concrete check for whoever's on the deferred-off variant: is the session launched with a per-run allowed_tools (cron job, delegate, or a profile that sets a caller allow-list), as distinct from the risk-profile one? If yes, add the mcp_abby__* names there (or drop the per-run list for that session) and the tools come back. If it reproduces with no caller list set at all, it's past this gate and promoting it to a tracked bug is the right call.

(For context on why I recognized the shape: I run an agent on this same deferred-tool pattern — name-only stubs, fetch-schema-before-call, a select: vs keyword search step. Different language, same mechanism.)

[susyabashti]

the risk_profiles.<profile_used>.allowed_tools is not set at all if that's what you mean.

[Audacity88]

@bryangruneberg @susyabashti thanks, the newer details make this look like more than a deferred-loading prompt/model issue.

A few things I’d separate:

• Dot-separated MCP tool names such as domains.list should be valid. ZeroClaw prefixes MCP tools as <server>__<tool>, so that would become something like mcp_abby__domains.list; I don’t think the dot itself explains tool_search being absent.
• With deferred_loading = true, tool_search should be present if the Zerocode session has at least one MCP stub admitted by the final tool policy. If the agent says it does not have tool_search, that suggests the runtime did not register it for that session, not just that the model failed to choose it.
• The gateway-vs-Zerocode difference is the strongest signal. Since the gateway can see the same MCP server/tools but Zerocode TUI cannot, the likely bug is somewhere in the Zerocode session’s MCP grant/policy/registration path.

I think this should now be tracked as a bug rather than left as general Q&A. I created an issue #8193 .

[bryangruneberg]

This is one of the most effective, proactive, and collaborative Open Source vibes I've experienced in like 25 years 🤯 freeking awesome and really motivating!

[Audacity88]

@bryangruneberg @susyabashti this should be fixed on master by #8199.

Root cause: Zerocode TUI Chat sessions were building the agent with MCP initialization disabled, so they skipped both deferred tool_search registration and eager <server>__<tool> registration. The gateway path did initialize MCP, which explains why gateway could see the tools while Zerocode could not.

The merged fix makes Chat-mode session/new initialize MCP, while keeping ACP/Code sessions on the old skip-MCP path. If you can still reproduce this on current master or the next release, please add the config shape and whether deferred_loading is on or off to #8193.

[bryangruneberg]

@Audacity88 - the MCP tools work well in the TUI with deferred_loading set to false, but if deferred_loading is set to true, it calls the tool_seach now, but it's still not finding the MCP.

Strangely, I was able to find something out about the MCP though 🤔

(FTR, my MCP server provides resources for identity, soul, etc. It also provides a skill, and some prompts`

You: tell me what mcp server you have available                                                                                █
(thinking) The user wants to know what MCP servers are available. I can use the `mcp_resources` tool with action "list" to see █
available resources from MCP servers, or I could use `tool_search` to find deferred MCP tools. Let me check both to give a     █
comprehensive answer.                                                                                                          █
[tool: mcp_resources]                                                                                                          █
  {"action":"list"}                                                                                                            █
  → [  {    "uri": "mcp_abby__tpv://bot/identity",    "name": "bot_identity",    "description": "The authenticated Bot's       █
self-identity markdown — who it is. Byte-identical to GET /api/v1/persona/ide…                                                 █
[tool: tool_search]                                                                                                            █
  {"max_results":50,"query":"*"}                                                                                               █
  → No matching deferred tools found.                                                                                          █
(thinking) The user asked what MCP servers I have available. From the results:1. `mcp_resources` returned resources from an MCP█
server called `mcp_abby` (prefix `mcp_abby__`). This appears to be a TPV (likely "The Personality Vector" or similar) MCP      █
server with resources about bot identity, soul, agents, user, and system skill.2. `tool_search` returned no deferred tools,    █
meaning there are no additional MCP tools loaded beyond what's already directly available.I should present this clearly to the █
user.                                                                                                                          █
Agent:                                                                                                                         █
You have one MCP server connected: mcp_abby (TPV — The Personality Vector).                                                    █
It exposes the following resources:                                                                                            █
┌──────────────────────────────┬──────────────┬────────────────────────────────────────────────────┐                          █
│ URI                          │ Name         │ Description                                         │                          █
├──────────────────────────────┼──────────────┼────────────────────────────────────────────────────┤                          █
│ mcp_abby__tpv://bot/identity │ bot_identity │ The bot's self-identity markdown                    │                          █
│ mcp_abby__tpv://bot/soul     │ bot_soul     │ The bot's behavioral rules and personality markdown │                          █
│ mcp_abby__tpv://bot/agents   │ bot_agents   │ The bot's Agents Workspace context markdown         │                          █
│ mcp_abby__tpv://bot/user     │ bot_user     │ Markdown describing the human the bot serves        │                          █
│ mcp_abby__tpv://system/skill │ system_skill │ Per-bot operating policy and surface model          │                          █
└──────────────────────────────┴──────────────┴────────────────────────────────────────────────────┘                          █
No additional deferred MCP tools were found beyond the ones already loaded in my toolset.                                      █                                                                                      

There seems to still be something "offwith the TUIchat` tab and MCPs.

Both deferred_loading=true and deferred_loading=false works if I call zeroclaw agent -a abby - so it defs seems to be a gremlin in zerocode

Attached is a redacted config.toml - example-config-toml.txt

I'm not sure about the correct protocol now... should I add this to #8193? Or should a new issue be opened?

[Audacity88]

Thanks, this is exactly the useful split.

Since deferred_loading = false works in Zerocode TUI now, #8199 did fix the earlier "Chat sessions skip MCP initialization entirely" bug. The remaining failure is narrower: with deferred_loading = true, Zerocode TUI now exposes tool_search and MCP resources, but the deferred MCP tool registry/search path is empty, while zeroclaw agent -a abby works in both modes.

I think this belongs on #8193 rather than a new issue, because it means the original TUI/MCP bug was only partially fixed. I'll reopen #8193 with this narrowed diagnosis and the redacted config link.

[CedricConday]

Building on @krotname — discovery logs are green, so transport is fine; the gap is between "registered with the gateway" and "told to the model." With deferred_loading = true, those 55 load as stubs and the model must invoke a tool-search step before it can see/call them. If the agent flow never triggers that step, it correctly reports no tools — they're behind the deferred gate.

• Quick fix: deferred_loading = false loads all 55 into the tool list directly — confirms the rest of your config is right.
• Keep deferred (context economy): make sure the search step is itself surfaced to the model and the agent is instructed to use it — if the search tool isn't in context, the model can't take the step, matching the "even with deferred off it's blank" case @susyabashti hit.

One caution either way: past ~40 tool schemas models start mis-selecting, so dumping all 55 raw has its own cost — deferred loading exists for exactly this, so the durable fix is a reliable search step, not loading all 55.

[Audacity88]

Small update from #8193: #8199 fixed the earlier Zerocode Chat case where MCP init was skipped entirely. With the newer state, deferred_loading = false works in Zerocode TUI.

The remaining bug is narrower: with deferred_loading = true, Zerocode TUI can see MCP resources and the model can call tool_search, but tool_search returns no deferred MCP tools. The same config works through zeroclaw agent -a abby in both eager and deferred modes.

So this no longer looks like transport/config, or only “the model did not take the search step.” It looks like the Zerocode Chat deferred tool registry/search path. Tracking that in #8193.

For now, deferred_loading = false is the practical workaround for the affected Zerocode TUI case.

[CedricConday]

Did some code-tracing on the deferred tool_search path to see where the TUI and zeroclaw agent -a abby actually diverge (master @ 68549a2). Sharing in case it saves time — I haven't runtime-confirmed the mechanism yet, so treat the last part as leads.

Both paths do build a populated tool_search. Chat/TUI: chat_session_new → Agent::from_config_with_tui_env (agent/agent.rs). CLI: agent/loop_.rs. Both construct ToolSearchTool::new(deferred_set, …) from DeferredMcpToolSet::from_registry, gated on allowed_stub_count > 0. So this isn't a missing registration — it's search-time filtering or a shadowing instance.

The regression test only checks presence, not results. chat_session_new_exposes_tool_search_in_deferred_mcp_mode asserts agent.tool_names() contains "tool_search" — it never invokes tool_search and checks that MCP stubs come back. That's how the suite stays green while the TUI returns nothing. A test that calls tool_search in a deferred chat session (the module already has start_mock_mcp_http_server + make_mcp_granting_config(…, deferred=true)) and asserts non-empty results should reproduce it and double as the regression guard. Happy to write that if it's useful.

Two candidate mechanisms I haven't confirmed:

1. caller_allowed filter asymmetry. In ToolAccessPolicy::is_tool_allowed, the risk-profile gate auto-admits MCP server__tool names (name.contains("__")), but the caller_allowed gate is strict exact-match with no such auto-admit. The CLI path builds its policy with the agent's allowed_tools as caller_allowed; agent.rs and gateway/lib.rs build it with None. Worth checking whether the tool_search instance the TUI actually queries ends up with a populated caller_allowed that strict-drops the prefixed names.

2. Two tool_search instances. gateway/lib.rs builds its own tool_search in addition to the agent's (agent.rs). In the TUI→gateway flow both exist; if the TUI hits the gateway-built one (different scope/policy), that would give "present but empty."

The test-gap is the concrete takeaway; #1/#2 are just leads. Let me know if a functional repro test would help.

[Audacity88]

thanks, this is a helpful split.
The concrete gap is the test one: chat_session_new_exposes_tool_search_in_deferred_mcp_mode proves that tool_search is present, but not that the deferred MCP stubs are actually searchable from a Zerocode Chat session. A functional regression test that invokes tool_search and asserts a known deferred MCP tool comes back would be useful, and it should be tracked against #8193.
I’d treat the caller_allowed and double-tool_search paths as investigation leads rather than conclusions until the test pins the failing path. If you want to open a small PR with the repro test first, that would give us a clean baseline before changing the wiring.

[CedricConday]

Quick follow-up with a concrete result. I wrote the functional test we discussed — it spins up a deferred-MCP Zerocode Chat session (via session/new), then actually invokes tool_search and asserts the granted MCP tool comes back (not just that tool_search is present).

On current master it passes. So the agent-construction path (Agent::from_config_with_tui_env) does populate tool_search with the deferred stubs correctly — the deferred registry/search is fine at the agent layer.

That narrows #8193 to the gateway path: zeroclaw-gateway builds its own tool_search (in gateway/lib.rs) separately from the agent's. In the TUI→gateway flow both exist, so the TUI is most likely hitting the gateway-built instance rather than the agent's populated one — that's the spot I'd look next.

Happy to (a) open a small PR with this passing test as a regression guard for the agent layer, and/or (b) dig into the gateway tool_search wiring — whatever's most useful to whoever's on it.

[bryangruneberg]

@CedricConday - I think I confirmed your suspicion: #8193 (comment)

[bryangruneberg]

#8193 (comment) I think this solves my issue 😁