Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mcp-use/mcp-use/llms.txt

Use this file to discover all available pages before exploring further.

​
What is an MCP Server?

An MCP Server exposes tools, resources, and prompts that AI agents can use through the Model Context Protocol. mcp-use provides a simple decorator-based API for creating production-ready MCP servers in Python.

​
Key Features

Simple Decorators

Define tools, resources, and prompts with intuitive decorators

Multiple Transports

Support for stdio, SSE, and streamable HTTP

Built-in Inspector

Debug mode with web UI for testing tools

Type Safety

Full type hints and Pydantic validation

Authentication

Built-in bearer token auth support

Middleware

Extensible middleware system

​
Quick Example

from mcp_use import MCPServer
from pydantic import Field
from typing import Annotated

server = MCPServer(
    name="my-server",
    version="1.0.0",
    instructions="A simple MCP server example"
)

@server.tool()
def get_weather(city: Annotated[str, Field(description="City name")]) -> dict:
    """Get weather for a city"""
    return {
        "temperature": 72,
        "condition": "sunny",
        "city": city
    }

if __name__ == "__main__":
    server.run()

​
Architecture

​
Core Concepts

​
Tools

Tools are functions that AI agents can call to perform actions: 
@server.tool(
    name="search",
    description="Search for information"
)
async def search(query: str) -> str:
    return f"Results for: {query}"

​
Resources

Resources provide read-only data that agents can access: 
@server.resource(
    uri="data://users",
    name="users",
    description="List of users"
)
async def get_users() -> str:
    return json.dumps([{"id": 1, "name": "Alice"}])

​
Prompts

Prompts are reusable templates for agent interactions: 
@server.prompt(
    name="greeting",
    description="Personalized greeting"
)
async def greeting(name: str) -> str:
    return f"Hello, {name}! How can I help you today?"

​
Transport Modes

​
Stdio Transport

For command-line integration and local development: 
server.run(transport="stdio")

​
HTTP Transport

For web-based integrations with server-sent events: 
server.run(
    transport="streamable-http",
    host="0.0.0.0",
    port=8000
)

​
Debug Mode

Enable debug mode to access development tools: 
server = MCPServer(
    name="my-server",
    debug=True  # Enables /docs, /inspector, /openmcp.json
)

server.run(port=8000)
Debug endpoints:
  • http://localhost:8000/docs - API documentation
  • http://localhost:8000/inspector - Interactive tool testing UI
  • http://localhost:8000/openmcp.json - OpenMCP metadata

​
Context Access

Access request context in your tools: 
from mcp.server.fastmcp import Context

@server.tool()
async def get_session_info(context: Context) -> dict:
    """Access session and request information"""
    return {
        "session_id": context.request_context.session_id,
        "capabilities": context.request_context.capabilities
    }

​
Error Handling

Return structured errors from tools: 
@server.tool()
async def divide(a: float, b: float) -> float:
    """Divide two numbers"""
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

​
Next Steps

Creating Servers

Learn to build MCP servers

Tools

Define server tools

Resources

Expose data resources

Transport

Configure transport protocols

Build docs developers (and LLMs) love

Get started for freeTalk to us