Skip to content

docs(sdk): document MCP tool refresh #694

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Shimada666 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(sdk): document MCP tool refresh #694

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions sdk/arch/tool-system.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -428,7 +428,8 @@ flowchart TB
- Wraps the MCP tool metadata in `MCPToolDefinition`
- Uses generic `MCPToolAction` as the action type (NOT dynamic models yet)
5. **Add to Agent** - All `MCPToolDefinition` instances are added to agent's `tools_map` during `initialize()` (bypasses ToolRegistry)
6. **Lazy Validation** - Dynamic Pydantic models are generated lazily when:
6. **Reconcile Changes** - When a server sends `notifications/tools/list_changed`, the SDK re-lists the server and atomically reconciles that client's tools in the running agent. Added tools appear, changed schemas replace their prior definitions, and removed tools disappear without altering historical tool-call events.
7. **Lazy Validation** - Dynamic Pydantic models are generated lazily when:
- `action_from_arguments()` is called (argument validation)
- `to_openai_tool()` is called (schema export to LLM)

Expand Down Expand Up @@ -465,6 +466,24 @@ agent = Agent(
)
```

### Refreshing Tools After an MCP Server Restart

Servers can change their advertised tools after a deployment or restart. Refresh
the conversation between runs to reconnect every configured MCP client and
reconcile the latest `tools/list` snapshot:

```python
conversation.refresh_mcp_tools()
conversation.send_message("Use the newly deployed tools")
conversation.run()
```

The same method works for local and remote conversations. Added tools become
available, changed definitions replace their previous schemas, and removed tools
are no longer exposed to subsequent LLM requests. Live MCP connections also
perform this reconciliation automatically when they receive
`notifications/tools/list_changed`.

## Component Relationships

```mermaid
Expand Down Expand Up @@ -501,7 +520,7 @@ flowchart TB

**Relationship Characteristics:**
- **Native → Registry → tools_map**: Native tools resolved via `ToolRegistry`
- **MCP → tools_map**: MCP tools bypass registry, added directly during `initialize()`
- **MCP → tools_map**: MCP tools bypass registry, are added during `initialize()`, and are reconciled after `tools/list_changed` notifications
- **tools_map → LLM**: Generate schemas describing all available capabilities
- **Agent → tools_map**: Execute actions, receive observations
- **tools_map → Conversation**: Read state for context-aware execution
Expand Down