language: system

files: ^(pyproject\.toml|uv\.lock)$

pass_filenames: false

language: system

pass_filenames: false

mcp.run(transport="streamable-http")

You can install this server in [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp) and interact with it right away. First, run the server:

Clients can provide a `list_roots_callback` so that servers can discover the client's workspace roots (directories, project folders, etc.):

from mcp import ClientSession, types

from mcp.shared.context import RequestContext

)

When a `list_roots_callback` is provided, the client automatically declares the `roots` capability (with `listChanged=True`) during initialization.

For servers that use the older SSE transport, use `sse_client()` from `mcp.client.sse`:

import asyncio

asyncio.run(main())

The `sse_client()` function accepts optional `headers`, `timeout`, `sse_read_timeout`, and `auth` parameters. The SSE transport is considered legacy; prefer [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http) for new servers.

Pass a `logging_callback` to receive log messages from the server:

from mcp import ClientSession, types

)

Request that the server change its minimum log level:

Either side can cancel a previously-issued request by sending a `CancelledNotification`:

import mcp.types as types

)

)

)

The `CancelledNotificationParams` fields:

- `requestId` (optional): The ID of the request to cancel. Required for non-task cancellations.

MCP uses [JSON Schema 2020-12](https://json-schema.org/draft/2020-12) for tool input schemas, output schemas, and elicitation schemas. When using Pydantic models, schemas are generated automatically via `model_json_schema()`:

from pydantic import BaseModel, Field

For FastMCP tools, input schemas are derived automatically from function signatures. For structured output, the output schema is derived from the return type annotation.

Resources with URI parameters (e.g., `{name}`) are registered as templates. When a client reads a templated resource, the URI parameters are extracted and passed to the function:

from mcp.server.fastmcp import FastMCP

return f'{{"user_id": "{user_id}", "name": "User {user_id}"}}'

Clients read a template resource by providing a concrete URI:

Resources can return binary data by returning `bytes` instead of `str`. Set the `mime_type` to indicate the content type:

from mcp.server.fastmcp import FastMCP

return f.read()

Binary content is automatically base64-encoded and returned as `BlobResourceContents` in the MCP response.

Clients can subscribe to resource updates. Use the low-level server API to handle subscription and unsubscription requests:

from mcp.server.lowlevel import Server

server = Server("Subscription Example")

subscriptions[str(uri)].discard("current_session")

When a subscribed resource changes, notify clients with `send_resource_updated()`:

Prompts can include embedded resources to provide file contents or data alongside the conversation messages:

import mcp.types as types

from mcp.server.fastmcp import FastMCP

]

Prompts can include images using `ImageContent` or the `Image` helper class:

import mcp.types as types

from mcp.server.fastmcp import FastMCP

]

When your server dynamically adds or removes prompts, notify connected clients:

from mcp.server.fastmcp import Context, FastMCP

from mcp.server.session import ServerSession

return "Prompts updated"

MCP servers can provide icons for UI display. Icons can be added to the server implementation, tools, resources, and prompts:

FastMCP provides an `Audio` class for returning audio data from tools, similar to `Image`:

from mcp.server.fastmcp import FastMCP

from mcp.server.fastmcp.utilities.types import Audio

return Audio(data=raw_audio, format="wav")

The `Audio` class accepts `path` or `data` (mutually exclusive) and an optional `format` string. Supported formats include `wav`, `mp3`, `ogg`, `flac`, `aac`, and `m4a`. When using a file path, the MIME type is inferred from the file extension.

Tools can return `EmbeddedResource` to attach file contents or data inline in the result:

from mcp.server.fastmcp import FastMCP

from mcp.types import EmbeddedResource, TextResourceContents

)

For binary embedded resources, use `BlobResourceContents` with base64-encoded data:

import base64

from mcp.types import BlobResourceContents, EmbeddedResource

@mcp.tool()

def read_binary_file(path: str) -> EmbeddedResource:

)

When your server dynamically adds or removes tools at runtime, notify connected clients so they can refresh their tool list:

from mcp.server.fastmcp import Context, FastMCP

from mcp.server.session import ServerSession

return f"Plugin '{name}' registered"

The Context object is automatically injected into tool and resource functions that request it via type hints. It provides access to MCP capabilities like logging, progress reporting, resource reading, user interaction, and request metadata.

To present a dropdown or selection list in elicitation forms, use `json_schema_extra` with an `enum` key on a `str` field. Do not use `Literal` -- use a plain `str` field with the enum constraint in the JSON schema:

from pydantic import BaseModel, Field

return "No color selected"

For URL mode elicitations, send a completion notification after the out-of-band interaction finishes. This tells the client that the elicitation is done and it may retry any blocked requests:

from mcp.server.fastmcp import Context, FastMCP

from mcp.server.session import ServerSession

@mcp.tool()

"""Called when OAuth flow completes out-of-band."""

# ... process the callback ...

return "Authorization complete"

Tools can interact with LLMs through sampling (generating text):

Clients can request a minimum logging level via `logging/setLevel`. Use the low-level server API to handle this:

import mcp.types as types

from mcp.server.lowlevel import Server

current_level = level

When this handler is registered, the server automatically declares the `logging` capability during initialization.