Add network metadata to MCP tool _meta field by andreidenissov-cog · Pull Request #769 · cognizant-ai-lab/neuro-san

andreidenissov-cog · 2026-02-26T22:35:17Z

NS-736 Allow --list option in agent_cli client for MCP connection.

Summary

For MCP tools/list responses, the agent network's metadata section (from the HOCON definition) is now included in the _meta field of each tool description. Note that this metadata is currently filtered to only include keys description, tags, and sample_queries.

Changes:

Added get_metadata() accessor to AgentNetwork to retrieve the metadata dict from the network config
Modified _get_tool_description in McpToolsProcessor to accept the AgentNetwork and populate _meta with the network metadata when present
Modified agent_cli tool to service --list request for MCP connection type
Extended McpServiceAgentSession class with list() request for listing MCP tools using agent networks metadata.

Review & Testing Checklist for Human

Verify that placing _meta at the tool object level (alongside name, description, inputSchema) is correct per MCP 2025-06-18 spec for tool annotations
Confirm that passing all metadata fields through to _meta is the desired behavior — no fields in the HOCON metadata section should be filtered or excluded from client visibility
The return type of get_metadata() is annotated as Dict[str, Any] but can return None — consider whether it should be Optional[Dict[str, Any]]
Test end-to-end with an MCP client: send a tools/list request against an agent network that has a metadata section and verify _meta appears correctly in the response; also test against one without metadata to confirm _meta is omitted

Notes

No new unit tests were added — existing tests pass but don't cover MCP tool listing
Requested by: @andreidenissov-cog
Link to Devin run: https://app.devin.ai/sessions/41d2f72b5b924a5d9f3568634e25c0d8

devin-ai-integration · 2026-02-26T22:35:27Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment and CI monitoring

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

neuro_san/service/mcp/processors/mcp_tools_processor.py:227

The type signature says this returns Dict[str, Any], but the function returns None when the agent is unauthorized or missing a service provider. Update the return type to Optional[Dict[str, Any]] (and propagate that to callers) to avoid misleading type hints and downstream None handling bugs.

    async def _get_tool_description(
            self,
            agent_name: str,
            agent_network: AgentNetwork,
            metadata: Dict[str, Any]) -> Dict[str, Any]:

        is_authorized: bool = False
        service_provider: AsyncAgentServiceProvider = None
        is_authorized, service_provider = await self.agent_policy.allow_agent(agent_name, metadata)

        if service_provider is None or not is_authorized:
            return None

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

For MCP list tools response, include the agent network definition metadata in the _meta part of each tool description so clients can access it. Add get_metadata() to AgentNetwork for clean access to the metadata section of the network config. Co-Authored-By: andrei.denissov <andrei.denissov@cognizant.com>

Make sure agent network metadata is a dictionary instance. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

andreidenissov-cog · 2026-03-04T18:42:03Z

neuro_san/service/mcp/processors/mcp_tools_processor.py

+        # List of keys we are interested in for MCP tool metadata - we can add more if necessary:
+        metadata_keys: List[str] = ["description", "sample_queries", "tags"]
+
+        network_metadata: Any = agent_network.get_metadata()
+        result_dict: Dict[str, Any] = {}
+        if isinstance(network_metadata, dict):
+            for key in metadata_keys:
+                if key in network_metadata:
+                    result_dict[key] = network_metadata[key]
+        if len(result_dict) > 0:


PR description updated.

Copilot · 2026-03-04T01:35:02Z

neuro_san/service/mcp/processors/mcp_tools_processor.py

+    async def get_agent_network_metadata(self, agent_network: AgentNetwork) -> Dict[str, Any]:
+        """
+        Get agent network metadata dictionary for MCP tool description.
+        :param agent_network: agent network object;
+        :return: metadata dictionary or None
+        """
+        # List of keys we are interested in for MCP tool metadata - we can add more if necessary:
+        metadata_keys: List[str] = ["description", "sample_queries", "tags"]
+
+        network_metadata: Any = agent_network.get_metadata()
+        result_dict: Dict[str, Any] = {}
+        if isinstance(network_metadata, dict):
+            for key in metadata_keys:
+                if key in network_metadata:
+                    result_dict[key] = network_metadata[key]
+        if len(result_dict) > 0:
+            return result_dict
+        return None


Type annotations don’t match behavior: get_agent_network_metadata() is annotated to return Dict[str, Any] but returns None when there’s no metadata, and callers treat it as optional. Update the return type to Optional[Dict[str, Any]] (and consider making the method non-async since it doesn’t await anything).

andreidenissov-cog · 2026-03-04T18:02:35Z

neuro_san/client/agent_cli.py

+        mcp_session: McpServiceAgentSession = self.session
+        response_dict: Dict[str, Any] = mcp_session.list({})
+        tools_list: List[Dict[str, Any]] = response_dict.get("result", {}).get("tools", [])
+        tools_description: List[Dict[str, Any]] = []
+        for tool in tools_list:
+            metadata: Dict[str, str] = tool.get("_meta", {})
+            tool_description: Dict[str, Any] = {
+                "agent_name": tool.get("name", "<Unnamed Tool>"),
+                "description": metadata.get("description", ""),
+                "tags": metadata.get("tags", [])
+            }
+            tools_description.append(tool_description)
+
+        empty_list: List[Dict[str, Any]] = []
+        if self.args.tags:
+            tags = set()
+            for tool_info in tools_description:
+                tool_tags: List[str] = tool_info.get("tags", empty_list)
+                tags.update(tool_tags)


Copilot · 2026-03-04T01:35:03Z

neuro_san/session/mcp_service_agent_session.py

+        path: str = self.get_request_path("list")
+        try:
+            with requests.post(path, json=mcp_payload, headers=headers,
+                               timeout=self.streaming_timeout_in_seconds) as response:


list() uses timeout=self.streaming_timeout_in_seconds, which is typically None for MCP sessions created by the CLI/factory, resulting in an unbounded HTTP request for a non-streaming call. Use the regular timeout_in_seconds (or a dedicated short timeout) for tools/list so the CLI doesn’t hang indefinitely when the MCP server is unreachable.

Suggested change

timeout=self.streaming_timeout_in_seconds) as response:

timeout=self.timeout_in_seconds) as response:

Good catch. Fixed.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

neuro_san/service/mcp/processors/mcp_tools_processor.py:228

_get_tool_description() is declared to return Dict[str, Any], but it returns None when the agent is not authorized / no provider is found. Please update the return type to Optional[Dict[str, Any]] (or refactor to always return a dict/error) so callers and type checkers can handle this correctly.

    async def _get_tool_description(
            self,
            agent_name: str,
            agent_network: AgentNetwork,
            metadata: Dict[str, Any]) -> Dict[str, Any]:

        is_authorized: bool = False
        service_provider: AsyncAgentServiceProvider = None
        is_authorized, service_provider = await self.agent_policy.allow_agent(agent_name, metadata)

        if service_provider is None or not is_authorized:
            return None

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-04T17:30:58Z

neuro_san/service/mcp/processors/mcp_tools_processor.py

+                    tool_dict: Dict[str, Any] = \
+                        await self._get_tool_description(agent_name, agent_network, metadata)
+                    if tool_dict is not None:
+                        tools_description.append(tool_dict)


tool_dict is annotated as Dict[str, Any] but _get_tool_description() can return None (see its early return). This makes the type hint incorrect and can mask real issues in static analysis; consider annotating tool_dict as Optional[Dict[str, Any]] (and/or make _get_tool_description always return a dict).

Copilot · 2026-03-04T17:30:58Z

neuro_san/service/mcp/processors/mcp_tools_processor.py

+    async def get_agent_network_metadata(self, agent_network: AgentNetwork) -> Dict[str, Any]:
+        """
+        Get agent network metadata dictionary for MCP tool description.
+        :param agent_network: agent network object;
+        :return: metadata dictionary or None
+        """
+        # List of keys we are interested in for MCP tool metadata - we can add more if necessary:
+        metadata_keys: List[str] = ["description", "sample_queries", "tags"]
+
+        network_metadata: Any = agent_network.get_metadata()
+        result_dict: Dict[str, Any] = {}
+        if isinstance(network_metadata, dict):
+            for key in metadata_keys:
+                if key in network_metadata:
+                    result_dict[key] = network_metadata[key]
+        if len(result_dict) > 0:
+            return result_dict
+        return None



get_agent_network_metadata() is marked async and annotated to return Dict[str, Any], but it contains no awaits and can return None. Consider making it a regular def and changing the return type to Optional[Dict[str, Any]] (and updating the call site) to better reflect its behavior.

neuro_san/client/agent_cli.py

+            tool_description: Dict[str, Any] = {
+                "agent_name": tool.get("name", "<Unnamed Tool>"),
+                "description": metadata.get("description", ""),
+                "tags": metadata.get("tags", [])


andreidenissov-cog · 2026-03-04T17:37:01Z

neuro_san/client/agent_cli.py

            return

        self.open_session()
+


For MCP mode, we need session to be opened - to execute initial handshake.

Makes sense — the MCP tools/list call requires the session to be established first (via the initialize / notifications/initialized handshake), so open_session() must run before mcp_list() can send the request.

andreidenissov-cog · 2026-03-04T18:05:33Z

neuro_san/client/agent_cli.py

+            tool_description: Dict[str, Any] = {
+                "agent_name": tool.get("name", "<Unnamed Tool>"),
+                "description": metadata.get("description", ""),
+                "tags": metadata.get("tags", [])


Extract description and tags from MCP tool metadata, so displayed data will be consistent with what we publish for agent networks.

Good approach — pulling description and tags from _meta keeps the CLI output aligned with the server-side metadata published in the tools/list response.

andreidenissov-cog · 2026-03-04T18:06:45Z

neuro_san/internals/graph/registry/agent_network.py

+                 or None if no metadata is defined.
+        """
+        return self.config.get("metadata", None)
+


Helper method for getting agent network metadata.

andreidenissov-cog · 2026-03-04T18:41:18Z

neuro_san/session/mcp_service_agent_session.py

            raise ValueError(self.help_message(path)) from exc

+    def list(self, request_dict: Dict[str, Any]) -> Dict[str, Any]:
+        """


We extend McpServiceAgentSession with list() API call from ConciergeSession to have all MCP-related functionality provided by a single session, initial handshake and all.

devin-ai-integration

Devin Review found 2 potential issues.

View 5 additional findings in Devin Review.

devin-ai-integration · 2026-03-09T17:42:30Z

neuro_san/client/agent_cli.py

🔴 "mcp" missing from --connection argparse choices, making --connection mcp fail

The choices parameter for --connection is ["direct", "http", "https"] but does not include "mcp". This means --connection mcp will be rejected by argparse with an error, even though the help text documents it as a valid choice and the rest of the code (main() at line 69) checks for self.args.connection == "mcp". While --mcp (the flag variant) works because store_const bypasses choices validation, the --connection mcp form that is documented in the help text is broken.

(Refers to line 281)

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-03-09T17:42:32Z

neuro_san/client/agent_cli.py

+            metadata: Dict[str, Any] = tool.get("_meta", {})
+            tool_description: Dict[str, Any] = {
+                "agent_name": tool.get("name", "<Unnamed Tool>"),
+                "description": metadata.get("description", ""),
+                "tags": metadata.get("tags", [])
+            }


🔴 mcp_list reads description/tags from _meta instead of tool-level fields, showing empty values for tools without HOCON metadata

In mcp_list(), the tool description and tags are read exclusively from the _meta sub-dictionary (tool.get("_meta", {})). However, on the server side (mcp_tools_processor.py:239-241), _meta is only populated when the agent network has a metadata section in its HOCON config. For tools without HOCON metadata, _meta won't be present, so tool.get("_meta", {}) returns {}, and the output will show an empty description and empty tags — even though the tool's top-level description field (populated from the agent's function description at mcp_tools_processor.py:232-235) contains a valid value. The description should fall back to tool.get("description", "") when _meta doesn't contain one.

Suggested change

metadata: Dict[str, Any] = tool.get("_meta", {})

tool_description: Dict[str, Any] = {

"agent_name": tool.get("name", "<Unnamed Tool>"),

"description": metadata.get("description", ""),

"tags": metadata.get("tags", [])

}

metadata: Dict[str, Any] = tool.get("_meta", {})

tool_description: Dict[str, Any] = {

"agent_name": tool.get("name", "<Unnamed Tool>"),

"description": metadata.get("description", tool.get("description", "")),

"tags": metadata.get("tags", [])

}

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration bot assigned andreidenissov-cog Feb 26, 2026

andreidenissov-cog requested a review from Copilot March 3, 2026 23:01

Copilot started reviewing on behalf of andreidenissov-cog March 3, 2026 23:02 View session

This comment was marked as resolved.

Sign in to view

andreidenissov-cog requested a review from Copilot March 3, 2026 23:12

Copilot started reviewing on behalf of andreidenissov-cog March 3, 2026 23:13 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

devin-ai-integration bot and others added 2 commits March 3, 2026 15:17

Apply suggestion from @Copilot

f997d03

Make sure agent network metadata is a dictionary instance. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

andreidenissov-cog force-pushed the ASD-NS-736-mcp-list01 branch from 634f86d to f997d03 Compare March 3, 2026 23:17

andreidenissov-cog added 2 commits March 3, 2026 15:57

WIP.

8ffbf49

Reformat tools descriptions.

a27ee31

andreidenissov-cog requested a review from Copilot March 4, 2026 01:31

Copilot started reviewing on behalf of andreidenissov-cog March 4, 2026 01:32 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

andreidenissov-cog and others added 2 commits March 3, 2026 17:40

Apply suggestion from @Copilot

856ede1

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fixes.

7e6ab1b

andreidenissov-cog requested a review from Copilot March 4, 2026 17:27

Copilot started reviewing on behalf of andreidenissov-cog March 4, 2026 17:28 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

andreidenissov-cog commented Mar 4, 2026

View reviewed changes

Fixes for Copilot.

ba4afe4

andreidenissov-cog commented Mar 4, 2026

View reviewed changes

Fix for timeout setting.

3a88504

devin-ai-integration bot reviewed Mar 9, 2026

View reviewed changes

	timeout=self.streaming_timeout_in_seconds) as response:
	timeout=self.timeout_in_seconds) as response:

Conversation

andreidenissov-cog commented Feb 26, 2026 • edited by devin-ai-integration bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Review & Testing Checklist for Human

Notes

Uh oh!

devin-ai-integration bot commented Feb 26, 2026

🤖 Devin AI Engineer

Uh oh!

This comment was marked as resolved.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

This comment was marked as resolved.

Uh oh!

andreidenissov-cog Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

andreidenissov-cog Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

andreidenissov-cog Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

andreidenissov-cog Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

andreidenissov-cog Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

andreidenissov-cog Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

andreidenissov-cog Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

andreidenissov-cog commented Feb 26, 2026 •

edited by devin-ai-integration bot

Loading