# Connect AutoGen to Axiom

**Transport:** stdio (autogen-ext[mcp] also supports HTTP/SSE)
**Auth:** local-stdio (Phase 0)
**Status:** Untested — recipe inferred from upstream docs

Microsoft AutoGen v0.4+ ships MCP tooling under `autogen-ext[mcp]`.
The integration converts MCP tools into AutoGen `Tool` objects usable
by any `AssistantAgent`, `RoundRobinGroupChat`, or custom workflow.

## Install prerequisites

```bash
pip install 'autogen-agentchat>=0.4' 'autogen-ext[mcp]>=0.4' 'autogen-core>=0.4'
```

Same Axiom prerequisites as the other recipes.

## Configure the connection

```python
import asyncio
from pathlib import Path

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.ui import Console
from autogen_ext.models.anthropic import AnthropicChatCompletionClient
from autogen_ext.tools.mcp import StdioMcpToolAdapter, StdioServerParams


async def main() -> None:
    server_params = StdioServerParams(
        command="/absolute/path/to/.venv/bin/axi",
        args=["mcp", "serve"],
        # env=None,  # add PYTHONPATH for worktree variant
    )
    tools = await StdioMcpToolAdapter.from_server(server_params)
    print(f"Loaded {len(tools)} Axiom tools")

    agent = AssistantAgent(
        name="axiom_diagnostician",
        model_client=AnthropicChatCompletionClient(model="claude-sonnet-4-5"),
        tools=tools,
        system_message=(
            "You inspect the local Axiom node via its MCP tools. "
            "Always show the raw JSON result of any tool call."
        ),
    )
    await Console(
        agent.run_stream(
            task="Call axiom_node__hooks_list with no arguments and report the JSON."
        )
    )


if __name__ == "__main__":
    asyncio.run(main())
```

Worktree variant:

```python
server_params = StdioServerParams(
    command="/absolute/path/to/.venv/bin/python3",
    args=["-m", "axiom.extensions.builtins.mcp.server"],
    env={"PYTHONPATH": "/absolute/path/to/axiom-checkout/src"},
)
```

## Verify

The script above prints the loaded count + streams the agent run. A
direct check:

```python
import asyncio
from autogen_ext.tools.mcp import StdioMcpToolAdapter, StdioServerParams


async def smoke() -> None:
    params = StdioServerParams(command="axi", args=["mcp", "serve"])
    tools = await StdioMcpToolAdapter.from_server(params)
    hooks = next(t for t in tools if t.name == "axiom_node__hooks_list")
    result = await hooks.run_json({}, cancellation_token=None)
    print(result)


asyncio.run(smoke())
```

Expected:

```json
{
  "node": "/Users/<you>/.axiom",
  "hooks_total": 0,
  "events_observed": [],
  "by_event": {}
}
```

## Notes

- AutoGen 0.4 is the v2 architecture (event-driven, async-first). The
  legacy `autogen` 0.2 API does not have first-class MCP support; if
  you're on 0.2, migrate to 0.4 before wiring MCP.
- For HTTP/SSE: `SseMcpToolAdapter` + `SseServerParams`; needs Axiom
  Phase 5 auth.
- AutoGen's tool-result handling expects JSON-serialisable returns. All
  Axiom tool handlers return JSON-serialisable dicts (per spec §5.1),
  so this is a no-op.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `from autogen_ext.tools.mcp import ...` fails | wrong package version | `pip install -U 'autogen-ext[mcp]'` |
| Adapter spawns then immediately exits | command crashes on init | Run manually; check `~/.axiom/logs/mcp/server.log` |
| Tool not appearing in agent's tool list | model didn't select it | Phrase task with explicit "use axiom_node__hooks_list" |

## References

- ADR-038 §D7
- AutoGen MCP docs: https://microsoft.github.io/autogen

_Copyright (c) 2026 B-Tree Ventures, LLC. Apache-2.0 licensed._
