Add MCP (Model Context Protocol) server support for external tool use

[aditya-pandey-dev]

Closes #240

Overview

This PR implements MCP (Model Context Protocol) integration for Concordia, enabling agents to use external tools during simulations.

What's Added

Core Infrastructure

• MCP Client Wrapper (concordia/tools/mcp_client.py)

  • Async/sync support via run_sync helper
  • MCPClientManager for multiple servers
  • Full connection lifecycle management

• File Reader MCP Server (concordia/tools/mcp_servers/file_reader_server.py)

  • Tools: read_file, list_directory, get_file_info
  • Security: restricted to /tmp and current working directory

Concordia Integration

• Tool Executor Component (concordia/components/game_master/mcp_tool_executor.py)

  • Automatic tool request detection from agent actions
  • LLM-based tool parsing
  • Result injection into agent memory

• Tool-Use GameMaster Prefab (concordia/prefabs/game_master/tool_use_gm.py)

  • Complete GM with MCP support built-in
  • Automatic tool availability notification to agents
  • Integrated tool execution pipeline

Documentation & Examples

• Example Notebook (examples/mcp_tool_use_example.ipynb)

  • Complete simulation with agent tool use
  • Mission briefing file reading scenario
  • Step-by-step demonstration

• README (concordia/tools/README.md)

  • Usage examples
  • Security guidelines
  • Custom server creation guide

Testing

• MCP server starts and responds correctly
• Client connects and lists tools successfully
• File reading works end-to-end
• GameMaster detects and executes tool requests
• Example notebook demonstrates complete workflow

Future Enhancements

As mentioned in the README, potential extensions include:

• Web search MCP server
• Database query MCP server
• REST API client MCP server
• Multi-modal tool support

[manaspros]

Really like the direction here, I've been thinking about MCP integration too.

One concern though — Concordia already has a Tool base class in concordia/document/tool.py. Adding a parallel concordia/tools/ module creates two separate tool-use surfaces which might confuse users about which to build on. Would it make more sense for MCPTool to wrap the existing Tool abstraction rather than live alongside it?

Also wondering if this belongs in contrib/ rather than core — similar to how contrib/language_models/ handles external API integrations that the core team can't easily keep up with as specs change. MCP is still evolving pretty fast.

Would love to see this land either way, just flagging the integration questions.

[vezhnick]

Hi Aditya!
Thanks for the PR. I would like to understand your use case a bit better.
There are several way to integrate tool use into the simulation. The one you propose here is through the actors submitting tool calls to the GM through their actions. The other possibility is actors making tool calls in their components. I have recently submitted a version of interactive document that support tool calls (concordia/document/interactive_document_tools.py).
The downside of using the GM as the tool interface is that it requires the actor to spend a whole turn to use the tool, on the other hand that could be the explicit mechanism that you want to model in the simulation.

I would also ask you to move the code into the contrib and use the existing tool abstraction (concordia/document/tool.py) . The notebook is fine in the in the examples, but tools, components and the prefab should go into contrib. Once the code is moved, I'll be happy to accept the PR.

Thank you for your contribution!

[aditya-pandey-dev]

Hi @vezhnick and @manaspros, I've addressed both review comments:
Moved all MCP code to concordia/contrib/ (tools, components, prefab)
Created MCPTool wrapper implementing concordia.document.tool.Tool
Notebook stays in examples/ as approved. Thank you for the feedback.

[aditya-pandey-dev]

@vezhnick Regarding the use case — the GM-based approach is intentional here. The goal is to model scenarios where an agent explicitly spends a turn to access external information (e.g., reading a file, querying an API), making the tool use visible and traceable in the simulation log. I'll look at interactive_document_tools.py as well — happy to align with that approach if you think it's more suitable.

[vezhnick]

Great. I think your use-case is valid and interesting, let's go with it.
In the PR there are some empty init.py in the concordia/tools, I think it's a leftover from before the move to contrib. There are also changes to actor_development notebook, which I recon are unintended?
Happy to accept the PR after the cleanup.

Thanks again!

[aditya-pandey-dev]

@vezhnick can you please review now i made some changes as you said! and sorry for the late reply

[vezhnick]

Great, almost there.
There are still some lngs:

And the last thing we need is for you to make contributor license agreement: https://cla.developers.google.com/

[aditya-pandey-dev]

@vezhnick I made the changes as you said. Can you please re-review it

[vezhnick]

Linter is still complaining:
Run pylint --errors-only notebooks
************* Module mcp_tool_use_example
notebooks/mcp_tool_use_example.py:174:0: E1142: 'await' should be used within an async function (await-outside-async)
notebooks/mcp_tool_use_example.py:175:9: E1142: 'await' should be used within an async function (await-outside-async)
notebooks/mcp_tool_use_example.py:176:0: E1142: 'await' should be used within an async function (await-outside-async)
Error: Process completed with exit code 2.

[aditya-pandey-dev]

Hi @vezhnick, all CI checks are now passing. The notebook has been updated with correct imports and type signatures. Ready for re-review!

[aditya-pandey-dev]

Hi @vezhnick, just following up on this PR. Let me know if anything else is needed — happy to address any further feedback. Thanks

[vezhnick]

LGTM