Feat/support mcp resources

[amri369]

Summary

Integrate MCP Resources. This allows MCP servers to expose data and content that can be read by clients and used as context for LLM interactions.

Key changes:

• Added three abstract methods to the to the base class MCPServer: list_resources, list_resource_templates and read_resource
• Implemented the abstract methods in the base class _MCPServerWithClientSession which is parent of classes MCPServerStdio, MCPServerSse , and MCPServerStreamableHttp.
• Created example MCP resources server with working demonstration.
• Updated documentation with MCP resources usage examples.

Note: This PR does not implement subscribe_resource and unsubscribe_resource methods.

Test plan

Unit tests: Added 4 comprehensive tests in tests/mcp/test_resources_server.py covering:

• Resources listing and retrieval
• Error handling for missing resource
• Integration tests: Updated existing MCP test suite to handle new abstract methods

Additionally, unit test test_handoff_prompt_is_correct has been added to increase coverage.

Example verification: Created working example with MCP resources server and client
All tests pass: 527/527 tests passing after adding optional dependencies

Issue number

Partially addresses #544 (resources only)

Checks

• I've added new tests (if relevant)
• I've added/updated the relevant documentation
• I've run make lint and make format
• I've made sure tests pass

[seratch]

Thanks for sending this PR! Will check it later this week.

[artificial-aidan]

Does this actually do anything to integrate MCP resources into the agent flow? Or is it up to the implementer to retrieve resources. Seems not very useful?

Tool calls can return links to resources, it seems like it would be more useful to parse tool outputs and use the resource link to return a resource to the LLM.

https://modelcontextprotocol.io/specification/2025-06-18/server/tools#resource-links

[amri369]

Does this actually do anything to integrate MCP resources into the agent flow? Or is it up to the implementer to retrieve resources. Seems not very useful?

Tool calls can return links to resources, it seems like it would be more useful to parse tool outputs and use the resource link to return a resource to the LLM.

https://modelcontextprotocol.io/specification/2025-06-18/server/tools#resource-links

Hey, thanks for the question!
All of the MCP-Resource helper methods live in _MCPServerWithClientSession, so any subclass that inherits from it—MCPServerStdio, MCPServerSse, or MCPServerStreamableHttp—already gets full access in run time to:

• list_resources
• list_resource_templates
• read_resource

[artificial-aidan]

Does anyone know if openai plans to support resource helper methods in open ai model calls? I experimented with something like this, which finds ResourceLinks in tool results and embeds the resource in the response instead

class MCPServerWithResourceLink(MCPServerStreamableHttp):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

    async def call_tool(self, tool_name: str, arguments: dict[str, t.Any] | None) -> CallToolResult:
        result = await super().call_tool(tool_name, arguments)
        new_contents = []
        for content in result.content:
            match content:
                case ResourceLink(
                    uri=uri,
                    annotations=annotations,
                ):
                    # Retrieve the resource and return it as an embedded resource
                    resource_result = await self.read_resource(uri)
                    for content in resource_result.contents:
                        new_contents.append(
                            EmbeddedResource(annotations=annotations, resource=content, type='resource')
                        )
                case _:
                    new_contents.append(content)
        return CallToolResult(
            content=new_contents,
            structuredContent=result.structuredContent,
            isError=result.isError,
        )