> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dedaluslabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging

> Debug MCP servers

MCP involves two processes talking over HTTP or stdio. Here's how to debug them.

## The tmux pattern

Run server and client in split terminals:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
tmux new-session -d -s mcp
tmux split-window -h
tmux send-keys -t mcp:0.0 'python server.py' C-m
sleep 2
tmux send-keys -t mcp:0.1 'python client.py' C-m
tmux attach -t mcp
```

See both outputs side by side. Kill when done: `tmux kill-session -t mcp`

## Structured logging

Log from inside tools:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from dedalus_mcp import get_context, tool

@tool(description="Process data")
async def process(data: str) -> dict:
    ctx = get_context()
    await ctx.debug("Starting", data={"length": len(data)})
    # ... work ...
    await ctx.info("Done", data={"result": 42})
    return {"ok": True}
```

## Verbose mode

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
await server.serve(verbose=True, log_level="debug")
```

Or via environment:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
LOG_LEVEL=debug python server.py
```

## Client-side log capture

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from dedalus_mcp.client import MCPClient, ClientCapabilitiesConfig

def log_handler(params):
    print(f"[{params.level}] {params.data}")

config = ClientCapabilitiesConfig(logging=log_handler)
client = await MCPClient.connect(url, capabilities=config)
```

## Common issues

**"Client does not advertise the sampling capability"**

Pass a sampling handler:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
config = ClientCapabilitiesConfig(sampling=sampling_handler)
client = await MCPClient.connect(url, capabilities=config)
```

**"Tool mutation attempted after server startup"**

Enable dynamic tools:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
server = MCPServer("my-server", allow_dynamic_tools=True)
```

**Connection refused**

Check the port: `lsof -i :8000`

Kill orphans: `lsof -ti :8000 | xargs kill -9`

**Wrong URL**

The endpoint is `http://127.0.0.1:8000/mcp`, not just `:8000`.

## When stuck

1. Strip to minimal reproduction
2. Check MCP spec compliance
3. Test with MCP Inspector: `pnpm dlx @anthropic/mcp-inspector`
4. Read server logs