# mcp_arena — Claude Code project prompt

> Paste this into Claude Code when working on a project that uses the
> `mcp_arena` Python library (v0.5.0). It gives you the current APIs,
> the full preset inventory, and the rules that avoid deprecated code.

## Role

You are working on a Python project that builds MCP (Model Context Protocol)
servers with `mcp_arena`. Use the guidance below instead of guessing APIs.

## Ground rules

- Python 3.12+ is required.
- An MCP server preset is a `BaseMCPServer` subclass in `mcp_arena/presents/<name>.py`.
- Register tools with `@self.mcp_server.tool()` inside `_register_tools()`; docstrings become tool descriptions.
- Credentials come from constructor kwargs or env vars (`GITHUB_TOKEN`, `CONTEXT7_API_KEY`, ...). Never hardcode secrets.
- Prefer stdio for local clients; use `sse` (`/sse`) or `streamable-http` (`/mcp`) for networked clients.
- The lazy loader AST-discovers every `*Server` class — dropping in a new file is enough to export it.

### Removed APIs — do NOT use these

- `ReactAgent`, `ReflectionAgent`, `PlanningAgent`, `RouterAgent`, `AgentFactory`
- `MCPLangChainWrapper`, `MCPLangChainIntegration`
- Canned tools: `CalculatorTool`, `FileSystemTool`, `SearchTool`, `WebTool`, `DataAnalysisTool`, `*MCPTools`

Use `make_mcp_agent`, `ToolRegistry` and `BaseTool` instead.

## Install

```bash
pip install mcp-arena                       # core: local_operation, generic_api, smtp
pip install "mcp-arena[context7,sentry]"   # individual presets
pip install "mcp-arena[all]"               # everything
pip install "mcp-arena[agents]"            # LangChain bridge
```

## Run a server

```python
from mcp_arena.presents.context7 import Context7MCPServer

server = Context7MCPServer()  # reads CONTEXT7_API_KEY if set

if __name__ == "__main__":
    server.run()              # stdio by default
```

```bash
mcp-arena run --mcp-server context7
```

## Inspect tools without an MCP client

```python
print(server.get_registered_tools())

from mcp_arena.wrapper import MCPAgentWrapper
for tool in MCPAgentWrapper(server).get_tools():
    print(tool["function"]["name"])
```

## Write a custom preset

```python
from mcp_arena.mcp.server import BaseMCPServer


class GreeterMCPServer(BaseMCPServer):
    def _register_tools(self):
        @self.mcp_server.tool()
        def greet(name: str) -> str:
            """Greet someone."""
            return f"Hello, {name}!"
```

## Agent bridge (LangChain / LangGraph)

```python
import asyncio
from mcp_arena.agent import make_mcp_agent, ToolRegistry, BaseTool
from mcp_arena.presents.context7 import Context7MCPServer


async def main():
    server = Context7MCPServer()
    agent = await make_mcp_agent(
        llm, [server],
        system_prompt="Use live library docs to answer questions.",
    )
    result = await agent.ainvoke({"messages": [{"role": "user", "content": "..."}]})
```

Filter tools before they reach the model:

```python
registry = ToolRegistry().register_server(server)
registry.keep("resolve_library_id", "query_docs")
agent = await make_mcp_agent(llm, [server], names=registry.names())
```

## Other frameworks

- AutoGen: `McpWorkbench` from `autogen_ext.tools.mcp` with `StdioServerParams`; pin `mcp<2`.
- LlamaIndex: `BasicMCPClient` + `McpToolSpec`; needs `mcp>=2`, so use a separate environment.
- Claude Desktop / Cursor / Cline: a `mcpServers` JSON entry pointing at `mcp-arena run --mcp-server <preset>`.
- Plain Python: `ClientSession` + `stdio_client` from the MCP SDK.

## CLI

```bash
mcp-arena list
mcp-arena info <preset>
mcp-arena validate <preset>
mcp-arena run --mcp-server <preset> --verbose
```

## Presets (32 server classes, 33 import paths)

- Communication: slack, whatsapp, gmail, outlook, smtp, mail, notification
- Dev platforms: github, gitlab, bitbucket
- Productivity: notion, confluence, jira
- Data & storage: postgres, mongo, redis, vectordb
- AI & monitoring: context7, sentry
- Cloud & system: aws, cloudstorage, docker, local_operation, screencapture
- Web & media: browser, webscraping, generic_api, image, video, audio, pdf, qrcode, spreadsheet

`gmail` is an import alias of `mail` (same `GmailMCPServer` class).

## Full documentation

- https://mcparena.vercel.app/docs
- https://mcparena.vercel.app/docs/mcp-arena/presets
- https://mcparena.vercel.app/docs/mcp-arena/integrations
- https://github.com/SatyamSingh8306/mcp_arena
