feat(mcp): surface a server's own instructions when it has no description

[yh928]

Summary

• Connection now keeps the instructions an MCP server returns from initialize, and ConnectedServerOverview carries them through to the prompt.
• The orchestrator's connected-server block falls back to those instructions only when the registry has no description, so nothing that reads well today changes.
• The text is untrusted third-party input reaching a system prompt, so it is sanitized and capped before use.

Problem

An MCP server's initialize response carries instructions — the server's own statement of what it is for and how to drive it. We asked for it, discarded it, and told the agent nothing.

That was survivable while every connected server came from the registry inventory, which carries a curated description. Hand-entered custom servers (#5033) have no inventory entry, so the orchestrator prompt listed them by name and tool count alone and the agent had to infer the server's purpose from tool names.

Solution

A three-step ladder in format_connected_mcp_block: registry description → server instructions → tool count. The description keeps priority deliberately — it is curated, the instructions are whatever the server author wrote.

Instructions pass through sanitize_for_llm with a 600-character cap and flattened newlines. This is a third party's text landing in our system prompt, so it is treated as untrusted the same way skill descriptions are.

Submission Checklist

• Tests added or updated (happy path + at least one failure / edge case) — three cases: instructions used when there is no description, description preferred when there is one, and untrusted instructions sanitized
• Diff coverage ≥ 80% — the ladder and the sanitize path are both covered by the new tests
• N/A: behaviour-only change, no feature row added/removed/renamed — Coverage matrix updated
• No new external network dependencies introduced
• N/A: no release-cut surface touched — Manual smoke checklist updated
• Linked issue closed via Closes #NNN in the ## Related section

Impact

• Prompt-surface only. A server that already has a registry description renders byte-identically.
• Security: the new text is untrusted and is sanitized on the way in; that is the only new data path.

Related

Closes #5317

Summary by CodeRabbit

• New Features

  • Connected MCP server overviews now include server-provided instructions when available.
  • Tool discovery descriptions now fall back to sanitized server instructions when registry descriptions are unavailable.
  • Existing descriptions remain prioritized, with tool-count information used as a final fallback.

• Bug Fixes

  • Added safeguards to prevent prompt-injection content in server instructions from affecting generated prompts.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c4350e53-08c0-4774-a847-1dcf0295e09b

📥 Commits

Reviewing files that changed from the base of the PR and between d75b0a4 and 9f6dbe8.

📒 Files selected for processing (3)

• src/openhuman/agent/registry/agents/orchestrator/prompt.rs
• src/openhuman/mcp/registry/connections.rs
• src/openhuman/mcp/registry/types.rs

🚧 Files skipped from review as they are similar to previous changes (3)

• src/openhuman/mcp/registry/types.rs
• src/openhuman/agent/registry/agents/orchestrator/prompt.rs
• src/openhuman/mcp/registry/connections.rs

---

📝 Walkthrough

Walkthrough

MCP connections now retain initialization instructions from stdio and HTTP servers. Connected-server overviews expose them. Orchestrator prompts use sanitized, length-bounded instructions when registry descriptions are unavailable, while preserving description and tool-count fallback precedence.

Changes

MCP instruction flow

Layer / File(s)	Summary
MCP metadata capture src/openhuman/mcp/registry/types.rs, src/openhuman/mcp/registry/connections.rs	Connections store initialization instructions from stdio and HTTP clients. Connected-server overviews include the stored instructions.
Prompt fallback and validation src/openhuman/agent/registry/agents/orchestrator/prompt.rs	The prompt uses sanitized and bounded server instructions after registry descriptions and before tool-count fallback. Tests cover precedence, sanitization, length bounding, and updated fixtures.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant MCPServer
  participant Connection
  participant ConnectedServerOverview
  participant OrchestratorPrompt
  MCPServer->>Connection: Return initialize instructions
  Connection->>ConnectedServerOverview: Store and expose instructions
  ConnectedServerOverview->>OrchestratorPrompt: Provide server metadata
  OrchestratorPrompt->>OrchestratorPrompt: Sanitize, bound, and apply fallback precedence

Loading

Possibly related PRs

• tinyhumansai/openhuman#4914: Introduced the connected-server overview extended by this change.
• tinyhumansai/openhuman#5396: Relates to prompt composition for connected-server integrations.

Suggested labels: feature, rust-core, agent

Suggested reviewers: m3ga-mind

Poem

I’m a rabbit with prompts in my paws,
MCP instructions now follow their cause.
Descriptions lead, clean guidance comes next,
Tool counts remain when no words are found in the text.
Hop, hop—sanitized context is bright!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the primary change: using MCP server instructions when no registry description exists.
Linked Issues check	✅ Passed	The changes preserve instructions, apply the required fallback order, retain description precedence, and sanitize and cap untrusted instructions [#5317].
Out of Scope Changes check	✅ Passed	All changes support MCP instruction preservation, prompt fallback behavior, precedence, sanitization, length limits, or related tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/openhuman/agent_registry/agents/orchestrator/prompt.rs`:
- Around line 669-686: Extend
connected_mcp_block_sanitizes_untrusted_instructions to use instructions
containing newline and tab characters plus content exceeding the 600-byte limit.
Assert the rendered server item is capped at the defined 600-byte boundary and
contains no newline or tab characters, while preserving the existing
instruction-fence sanitization and server-name assertions.

In `@src/openhuman/mcp_registry/connections.rs`:
- Around line 174-178: Add stdio and HTTP connection tests covering the
initialization-to-overview propagation: have each initialize branch return
distinct instructions, then assert the resulting connected_overview retains the
corresponding value from Connection.instructions. Update the existing connection
test coverage near the initialize and overview construction paths without
changing production behavior.

In `@src/openhuman/mcp_registry/types.rs`:
- Around line 75-78: Add focused tests for the Transport::is_http_remote
discriminator, asserting Transport::Stdio returns false and
Transport::HttpRemote returns true. Place the coverage alongside the existing
Transport tests and construct each variant with the required fields.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 64b7d89f-789d-449f-bb72-a85d2f13c6f5

📥 Commits

Reviewing files that changed from the base of the PR and between a52a599 and a80330c.

📒 Files selected for processing (3)

• src/openhuman/agent_registry/agents/orchestrator/prompt.rs
• src/openhuman/mcp_registry/connections.rs
• src/openhuman/mcp_registry/types.rs

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a80330cee1

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[greptile-apps]

Greptile Summary

This PR surfaces MCP server instructions (from the initialize handshake) in the orchestrator prompt as a fallback for custom servers that have no registry description, sanitizing the text through sanitize_for_llm with a 600-byte cap. The three-step ladder (registry description → server instructions → tool-count) is a clean design and the security intent is sound.

• Connection and ConnectedServerOverview now carry instructions: Option<String>, populated from both Stdio and HttpRemote initialize calls.
• format_connected_mcp_block in prompt.rs adds the fallback branch and three well-scoped tests, but references crate::openhuman::mcp_client::sanitize::sanitize_for_llm — a module path that does not exist; the correct path used elsewhere is crate::openhuman::util::sanitize::sanitize_for_llm, and this will fail to compile.

Confidence Score: 2/5

Not safe to merge: the instructions sanitization in prompt.rs references crate::openhuman::mcp_client::sanitize, a module that does not exist, which will cause a compile failure.

The only changed file that is not straightforwardly correct is prompt.rs, where the new instructions sanitization call uses crate::openhuman::mcp_client::sanitize::sanitize_for_llm — a path that resolves to nothing in this codebase. Every other call site uses crate::openhuman::util::sanitize::sanitize_for_llm. The build will fail until this is corrected.

Files Needing Attention: src/openhuman/agent/registry/agents/orchestrator/prompt.rs — the wrong sanitize module path on the instructions branch.

Important Files Changed

Filename	Overview
src/openhuman/agent/registry/agents/orchestrator/prompt.rs	Adds instruction fallback and three tests; the instructions sanitization call references a non-existent module path (mcp_client::sanitize vs util::sanitize), causing a compile failure.
src/openhuman/mcp/registry/connections.rs	Correctly captures init.instructions from both Stdio and HttpRemote branches and threads it through to Connection and connected_overview.
src/openhuman/mcp/registry/types.rs	Adds instructions: Option<String> field to ConnectedServerOverview with clear documentation; straightforward and correct.

_{Reviews (3): Last reviewed commit: "feat(mcp): surface a server's own instru..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/openhuman/mcp_registry/types.rs`:
- Around line 195-208: Add coverage in the mcp_registry test module for
format_connected_mcp_block() and serializable ConnectedServerOverview data:
verify a non-empty description takes precedence over instructions, instruction
text is sanitized before rendering, and the rendered instruction fallback is
capped at 600 bytes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ff9b3c43-077e-4751-8fb5-184232aec0ee

📥 Commits

Reviewing files that changed from the base of the PR and between a80330c and 2073e7f.

📒 Files selected for processing (3)

• src/openhuman/agent_registry/agents/orchestrator/prompt.rs
• src/openhuman/mcp_registry/connections.rs
• src/openhuman/mcp_registry/types.rs

🚧 Files skipped from review as they are similar to previous changes (2)

• src/openhuman/agent_registry/agents/orchestrator/prompt.rs
• src/openhuman/mcp_registry/connections.rs

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/openhuman/agent/registry/agents/orchestrator/prompt.rs`:
- Around line 207-232: Split the oversized files by extracting the connected-MCP
block formatting around prompt.rs lines 207-232 into a focused module, and move
its formatter tests from prompt.rs lines 613-686 alongside it; update prompt.rs
to call the extracted formatter while preserving current description,
instructions sanitization, and fallback behavior. Extract the connection
initialization workflow from connections.rs lines 404-481 into a focused MCP
registry module, updating callers and imports without changing its behavior.
Ensure the resulting files remain at or below 500 lines.

In `@src/openhuman/mcp/registry/connections.rs`:
- Around line 417-418: Update the initialize call in the active client setup
flow around stdio.initialize() and the corresponding additional transport path
to emit [rpc] debug events immediately before and after each RPC. Include
server_id and transport on both events, and include instructions_present on the
completion event without logging instruction contents; preserve the existing
initialization result and error propagation.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a970da01-e469-4e8c-badc-9331f2b0fe6e

📥 Commits

Reviewing files that changed from the base of the PR and between d75b0a4 and 3c96df9.

📒 Files selected for processing (3)

• src/openhuman/agent/registry/agents/orchestrator/prompt.rs
• src/openhuman/mcp/registry/connections.rs
• src/openhuman/mcp/registry/types.rs

[greptile-apps]

yh928 has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[greptile-apps]

yh928 has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[M3gA-Mind]

Maintainer review pass (review only — no approval, and nothing pushed to your branch). Checked against current main (fa044d388) and against the pinned vendor/tinymcp (55483d236).

The idea is good and still wanted — but this PR has become a cross-repo change, and I don't think that's obvious from the conflict output. Please read §1 before you attempt the rebase; two of your three files can no longer be edited in this repo at all.

1. connections.rs and types.rs are gone, and their contents moved to tinymcp

git reports:

CONFLICT (modify/delete): src/openhuman/mcp/registry/connections.rs deleted in main and modified in this branch
CONFLICT (modify/delete): src/openhuman/mcp/registry/types.rs      deleted in main and modified in this branch

Both were removed in b586de87e — "Remove files resurrected by a mistaken checkout" — as part of a batch that also took out mcp/audit/, mcp/config_servers/ and mcp/http_client/. They are not coming back.

The module paths survive, which is what makes this confusing: mcp/registry/mod.rs still declares pub mod types and pub mod connections, but they are now thin re-export shims —

pub mod types {
    pub use tinymcp_bus::{ …, ConnectedServerOverview, … };
}

pub mod connections {
    pub use tinymcp_bus::ConnectedServerOverview;
    pub async fn connected_overview() -> Vec<ConnectedServerOverview> {
        match host::try_service() { Some(s) => s.dynamic().connected_overview().await, None => Vec::new() }
    }
}

tinymcp owns the connection map now; openhuman only looks through it. So your +42/-5 and +13/-1 hunks have no file to land in — ConnectedServerOverview is defined at crates/tinymcp-bus/src/registry/types.rs:247 in tinyhumansai/tinymcp, and at the pinned commit its fields are exactly server_id, qualified_name, display_name, description, tools. No instructions.

The good news, and it is genuinely good: tinymcp already captures what you need. crates/tinymcp-bus/src/transport/types.rs:169 has

/// Free-form guidance the server wants the client to have.
///
/// Untrusted remote text. Sanitize before placing it in an LLM's context.
#[serde(default)]
pub instructions: Option<String>,

on the initialize-handshake type — parsed, retained, and already carrying the exact untrusted-text warning your design is built around. So the upstream work is not "capture instructions"; it is only "carry the field one layer up into ConnectedServerOverview". That is a small change.

There is also a nice piece of corroboration for your premise sitting in that struct's own doc comment: tools is documented as "Kept in full so a host can fall back to a tool count when a server has no description" — the fallback you are trying to improve on is described upstream as the current state of the art.

What this means in practice

This becomes three deliverables, in order:

1. tinyhumansai/tinymcp — add instructions: Option<String> to ConnectedServerOverview and populate it from the retained handshake value. #[serde(default)] keeps the bus contract backward-compatible.
2. tinyhumansai/openhuman — bump the vendor/tinymcp gitlink to the commit from (1). Worth saying out loud because it is easy to assume the pin bump rides along with the upstream merge: it does not, and a merged upstream PR delivers nothing to this repo until the pin moves.
3. This PR — keep only the prompt.rs hunks, rebased on (2).

If you'd rather not carry a cross-repo change, say so on this PR and I'll flag it to the maintainers — the openhuman half is small enough that it may be worth someone else taking the tinymcp side.

2. The prompt.rs half rebases cleanly and is unaffected

format_connected_mcp_block is still at prompt.rs:180, still takes &[…connections::ConnectedServerOverview], and still does the description-sanitize dance your ladder slots into. Its conflict is ordinary content drift, not a relocation. Once the field exists, this half is a straight rebase.

3. One small thing to reconcile while you're there

prompt.rs currently caps both untrusted strings at 240 bytes — skill descriptions at :143 and MCP descriptions at :218 — and your instructions cap is 600. I don't think that's wrong (instructions are a paragraph by nature, descriptions are a line), but three sanitize calls in one file with two different caps will draw a reviewer's question. A half-sentence on why 600 is the right number for this one input would settle it in advance.

Otherwise this is in good shape

Every check is green (14 pass, 6 skipped), CodeRabbit approved, and there are no unresolved review threads. The design calls — registry description keeps priority over server-authored text, and the instructions go through sanitize_for_llm because they are a third party's words landing in a system prompt — are both the right ones, and the second is the reason this needs to be done carefully rather than quickly. None of §1 is a criticism of the work; the ground moved under it.

[yh928]

Confirmed against main (8e65c4008) and the pinned vendor/tinymcp — your §1 is right and it changes what this PR is.

mcp/registry/{connections,types}.rs are re-export shims over tinymcp_bus now, so ConnectedServerOverview is defined in tinyhumansai/tinymcp and the +42/-5 and +13/-1 hunks have no file to land in. What is not affected is the part that carries the idea: agent/registry/agents/orchestrator/prompt.rs still exists and format_connected_mcp_block is still the function that decides what a connected server's line says. That change applies cleanly.

So the dependency is narrow and one-directional — one field:

• tinymcp — add instructions: Option<String> to ConnectedServerOverview, populated from the server's initialize handshake (the protocol already returns it; it is being dropped).
• openhuman — this PR's format_connected_mcp_block change, unchanged: fall back to instructions only when the registry description is empty, through the same sanitize_for_llm scrub at a wider bound, and keep the tool-count fallback beneath both. Its three tests need instructions: added to the existing ConnectedServerOverview literals, which is mechanical.

Nothing about the reasoning changed: a hand-added server has no registry entry and so no description, and its own initialize instructions are the only thing that can tell the orchestrator what it is for — otherwise the line degrades to a name plus "N tools available", which is what it does today.

I have not opened the tinymcp PR — different repo, its own review, and not something to do silently as part of a rebase. Options:

1. Add the field upstream in tinymcp, then rebase this PR down to the prompt change alone (it becomes small and self-contained); or
2. Close this and refile once the field exists.

(1) is my preference. Happy to open it on your say-so.

[yh928]

Upstream PR opened: tinyhumansai/tinymcp#14

That is the half that had to move. Once it merges this PR reduces to the openhuman-side consumer change (plus a submodule bump), which I'll rebase down to then.