Improve MCP tool compatibility and documentation

cpsievert · claude · cpsievert · commit 119ca37ea523 · 2026-01-02T18:45:15.000-06:00
- Add `strict` parameter to Tool class to support OpenAI's strict mode - Set strict=False for MCP tools to preserve optional params (MCP uses standard JSON Schema conventions where optional params aren't in required) - Add `sanitize_schema()` function that strips `format` field (e.g., "uri") which OpenAI rejects, in addition to existing `title` removal - Restructure MCP tools guide with practical Quick Start example using MCP Fetch server - Update MCP server link to glama.ai/mcp/servers - Add section headers for Registering tools vs Authoring tools - Rename "Motivating example" to "Advanced example: Code execution" 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/chatlas/_tools.py b/chatlas/_tools.py
@@ -71,19 +71,26 @@ def __init__(
         description: str,
         parameters: dict[str, Any],
         annotations: "Optional[ToolAnnotations]" = None,
+        strict: Optional[bool] = None,
     ):
         self.name = name
         self.func = func
         self.annotations = annotations
         self._is_async = _utils.is_async_callable(func)
-        self.schema: "ChatCompletionToolParam" = {
-            "type": "function",
-            "function": {
-                "name": name,
-                "description": description,
-                "parameters": parameters,
-            },
+        func_schema: dict[str, Any] = {
+            "name": name,
+            "description": description,
+            "parameters": parameters,
         }
+        if strict is not None:
+            func_schema["strict"] = strict
+        self.schema: "ChatCompletionToolParam" = cast(
+            "ChatCompletionToolParam",
+            {
+                "type": "function",
+                "function": func_schema,
+            },
+        )
 
     @classmethod
     def from_func(
@@ -226,6 +233,9 @@ async def _call(**args: Any) -> AsyncGenerator[ContentToolResult, None]:
             description=mcp_tool.description or "",
             parameters=params,
             annotations=annotations,
+            # MCP tools use standard JSON Schema conventions for optional params
+            # (not in required array), which requires strict=False for OpenAI
+            strict=False,
         )
 
 
@@ -441,25 +451,37 @@ def _validate_model_vs_function(model: type[BaseModel], func: Callable) -> None:
 def mcp_tool_input_schema_to_param_schema(
     input_schema: dict[str, Any],
 ) -> dict[str, object]:
-    params = rm_param_titles(input_schema)
+    params = sanitize_schema(input_schema)
 
     if "additionalProperties" not in params:
         params["additionalProperties"] = False
 
     return params
 
 
-def rm_param_titles(
+def sanitize_schema(
     params: dict[str, object],
 ) -> dict[str, object]:
-    # For some reason, pydantic wants to include a title at the model and field
-    # level. I don't think we actually need or want this.
+    """
+    Sanitize JSON Schema for provider compatibility.
+
+    - `title`: Pydantic includes titles at model/field level, but they're not needed
+    - `format`: JSON Schema format hints (e.g., "uri", "date-time") that some
+      providers like OpenAI reject
+    """
     if "title" in params:
         del params["title"]
 
+    if "format" in params:
+        del params["format"]
+
     if "properties" in params and isinstance(params["properties"], dict):
         for prop in params["properties"].values():
-            if "title" in prop:
-                del prop["title"]
+            if isinstance(prop, dict):
+                sanitize_schema(prop)
 
     return params
+
+
+# Keep for backwards compatibility
+rm_param_titles = sanitize_schema
diff --git a/docs/misc/mcp-tools.qmd b/docs/misc/mcp-tools.qmd
@@ -3,67 +3,101 @@ title: MCP tools
 callout-appearance: simple
 ---
 
-[Model Context Protocol (MCP)](https://modelcontextprotocol.io) provides a standard 
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io) provides a standard
 way to build services that LLMs can use to gain context.
-Most significantly, MCP provides a standard way to serve [tools](../get-started/tools.qmd) (i.e., functions) for an LLM to call from another program or machine.
-As a result, there are now [many useful MCP server implementations available](https://github.com/punkpeye/awesome-mcp-servers?tab=readme-ov-file#server-implementations) to help extend the capabilities of your chat application.
-In this article, you'll learn the basics of implementing and using MCP tools in chatlas.
+This includes a standard way to provide [tools](../get-started/tools.qmd) (i.e., functions) for an LLM to call from another program or machine.
+There are now [many useful MCP server implementations available](https://glama.ai/mcp/servers) to help extend the capabilities of your chat application with minimal effort.
 
+In this article, you'll learn how to both register existing MCP tools with chatlas as well as author your own custom MCP tools.
 
 ::: callout-note
 ## Prerequisites
 
-To leverage MCP tools from chatlas, you'll need to install the `mcp` library.
+To leverage MCP tools from chatlas, you'll want to install the `mcp` extra.
 
 ```bash
 pip install 'chatlas[mcp]'
 ```
 :::
 
 
-## Basic usage
+## Registering tools
 
-Chatlas provides two ways to register MCP tools: [`.register_mcp_tools_http_stream_async()`](../reference/Chat.qmd#register_mcp_tools_http_stream_async) and [`.register_mcp_tools_stdio_async()`](../reference/Chat.qmd#register_mcp_tools_stdio_async).
+### Quick start {#quick-start}
 
+Let's start with a practical example: using the [MCP Fetch server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) to give an LLM the ability to fetch and read web pages.
+This server is maintained by Anthropic and can be run via `uvx` (which comes with [uv](https://docs.astral.sh/uv/)).
 
-The main difference is how they interact with the MCP server: the former connects to an already running HTTP server, while the latter executes a system command to run the server locally.
-Roughly speaking, usage looks something like this:
-
-::: panel-tabset
-
-### Streaming HTTP
+For simplicity and convenience, we'll use the [`.register_mcp_tools_stdio_async()`](../reference/Chat.qmd#register_mcp_tools_stdio_async) method to both run the MCP Fetch server locally and register its tools with our `ChatOpenAI` instance:
 
 ```python
+import asyncio
 from chatlas import ChatOpenAI
 
-chat = ChatOpenAI()
+async def main():
+    chat = ChatOpenAI()
+    await chat.register_mcp_tools_stdio_async(
+        command="uvx",
+        args=["mcp-server-fetch"],
+    )
+    await chat.chat_async(
+        "Summarize the first paragraph of https://en.wikipedia.org/wiki/Python_(programming_language)"
+    )
+    await chat.cleanup_mcp_tools()
 
-# Assuming you have an MCP server running at the specified URL
-await chat.register_mcp_tools_http_stream_async(
-    url="http://localhost:8000/mcp",
-)
+asyncio.run(main())
 ```
 
-### Stdio (Standard Input/Output)
-
+::: chatlas-response-container
 ```python
-from chatlas import ChatOpenAI
+# 🔧 tool request
+fetch(url="https://en.wikipedia.org/wiki/Python_(programming_language)")
+```
+
+Python is a high-level, general-purpose programming language known for its emphasis on code readability through significant indentation. It supports multiple programming paradigms including structured, object-oriented, and functional programming, and is dynamically typed with garbage collection.
+:::
+
+::: callout-tip
+### Built-in fetch/search tools
+
+For providers with native web fetch support (Claude, Google), consider using [`tool_web_fetch()`](../reference/tool_web_fetch.qmd) instead -- it's simpler and doesn't require MCP setup.
+Similarly, [`tool_web_search()`](../reference/tool_web_search.qmd) provides native web search for OpenAI, Claude, and Google.
+:::
 
-chat = ChatOpenAI()
 
-# Assuming my_mcp_server.py is a valid MCP server script
+### Basic usage {#basic-usage}
+
+Chatlas provides two ways to register MCP tools:
+
+1. Stdio ([`.register_mcp_tools_stdio_async()`](../reference/Chat.qmd#register_mcp_tools_stdio_async))
+2. Streamble HTTP [`.register_mcp_tools_http_stream_async()`](../reference/Chat.qmd#register_mcp_tools_http_stream_async).
+
+The main difference is how they communicate with the MCP server: the former (Stdio) executes a system command to run the server locally, while the latter (HTTP) connects to an already running HTTP server.
+
+This makes the Stdio method more ergonomic for local development and testing. For instance, recall the example above, which runs `uvx mcp-server-fetch` locally to provide web fetching capabilities to the chat instance:
+
+```python
+# Run a server via uvx, npx, or any other command
 await chat.register_mcp_tools_stdio_async(
-    command="mcp",
-    args=["run", "my_mcp_server.py"],
+    command="uvx",
+    args=["mcp-server-fetch"],
 )
 ```
 
-:::
+On the other hand, the HTTP method is better for production environments where the server is hosted remotely or in a longer-running process.
+For example, if you have an MCP server already running at `http://localhost:8000/mcp`, you can connect to it as follows:
+
+```python
+# Connect to a server already running at the specified URL
+await chat.register_mcp_tools_http_stream_async(
+    url="http://localhost:8000/mcp",
+)
+```
 
 ::: callout-warning
 ### Async methods
 
-For performance reasons, the methods for registering MCP tools are asynchronous, so you'll need to use `await` when calling them. 
+For performance, the methods for registering MCP tools are asynchronous, so you'll need to use `await` when calling them.
 In some environments, such as Jupyter notebooks and the [Positron IDE](https://positron.posit.co/) console, you can simply use `await` directly (as is done above).
 However, in other environments, you may need to wrap your code in an `async` function and use `asyncio.run()` to execute it.
 The examples below use `asyncio.run()` to run the asynchronous code, but you can adapt them to your environment as needed.
@@ -75,23 +109,14 @@ Note that these methods work by:
 2. Requesting the available tools and making them available to the chat instance
 3. Keeping the connection open for tool calls during the chat session
 
+This means, when you no longer need the MCP tools, it's good practice to clean up the connection to the MCP server, as well `Chat`'s tool state.
+This is done by calling [`.cleanup_mcp_tools()`](../reference/Chat.qmd#cleanup_mcp_tools) at the end of your chat session (the examples demonstrate how to do this).
 
-::: callout-warning
-### Cleanup
-
-When you no longer need the MCP tools, it's important to clean up the connection to the MCP server, as well `Chat`'s tool state.
-This is done by calling [`.cleanup_mcp_tools()`](../reference/Chat.qmd#cleanup_mcp_tools) at the end of your chat session (the examples demonstrate how to do this). 
-:::
-
-
-## Basic example
-
-Let's walk through a full-fledged example of using MCP tools in chatlas, including implementing our own MCP server.
+## Authoring tools
 
-### Basic server {#basic-server}
+If existing MCP servers don't meet your needs, you can implement your own without much effort thanks to the [mcp](https://pypi.org/project/mcp/) Python library (you can also [work in other languages](https://modelcontextprotocol.io/docs/sdk), if you like).
 
 Below is a basic MCP server with a simple `add` tool to add two numbers together.
-This particular server is implemented in Python (via [mcp](https://pypi.org/project/mcp/)), but remember that MCP servers can be implemented in any programming language.
 
 ```python
 from mcp.server.fastmcp import FastMCP
@@ -103,14 +128,15 @@ def add(x: int, y: int) -> int:
     return x + y
 ```
 
+That's it! You can now run this server through the streaming HTTP or Stdio protocols and connect its tools to chatlas.
 
 ### HTTP Stream
 
 The `mcp` library provides a CLI tool to run the MCP server over HTTP transport.
 As long as you have `mcp` installed, and the [server above](#basic-server) saved as `my_mcp_server.py`, this can be done as follows:
 
 ```bash
-$ mcp run -t sse my_mcp_server.py 
+$ mcp run -t sse my_mcp_server.py
 INFO:     Started server process [19144]
 INFO:     Waiting for application startup.
 INFO:     Application startup complete.
@@ -141,12 +167,12 @@ asyncio.run(do_chat("What is 5 - 3?"))
 ::: chatlas-response-container
 
 ```python
-# 🔧 tool request                        
+# 🔧 tool request
 add(x=5, y=-3)
 ```
 
 ```python
-# ✅ tool result                  
+# ✅ tool result
 2
 ```
 
@@ -186,27 +212,27 @@ asyncio.run(do_chat("What is 5 - 3?"))
 ::: chatlas-response-container
 
 ```python
-# 🔧 tool request                        
+# 🔧 tool request
 add(x=5, y=-3)
 ```
 
 ```python
-# ✅ tool result                  
+# ✅ tool result
 2
 ```
 
 5 - 3 equals 2.
 :::
 
 
-## Motivating example
+## Advanced example: Code execution
 
 Let's look at a more compelling use case for MCP tools: code execution.
 A tool that can execute code and return the results is a powerful way to extend the capabilities of an LLM.
 This way, LLMs can generate code based on natural language prompts (which they are quite good at!) and then execute that code to get precise and reliable results from data (which LLMs are not so good at!).
 However, allowing an LLM to execute arbitrary code is risky, as the generated code could potentially be destructive, harmful, or even malicious.
 
-To mitigate these risks, it's important to implement safeguards around code execution. 
+To mitigate these risks, it's important to implement safeguards around code execution.
 This can include running code in isolated environments, restricting access to sensitive resources, and carefully validating and sanitizing inputs to the code execution tool.
 One such implementation is Pydantic's [Run Python MCP server](https://github.com/pydantic/pydantic-ai/tree/main/mcp-run-python), which provides a sandboxed environment for executing Python code safely via [Pyodide](https://pyodide.org/en/stable/) and [Deno](https://deno.com/).
 
@@ -242,4 +268,4 @@ async def _(user_input: str):
     await chat.append_message_stream(stream)
 ```
 
-![Screenshot of a LLM executing Python code via a tool call in a Shiny chatbot](../images/shiny-mcp-run-python.png){class="shadow rounded"}
+![Screenshot of a LLM executing Python code via a tool call in a Shiny chatbot](../images/shiny-mcp-run-python.png){class="shadow rounded"}
