mcp-use

https://docs.mcp-use.com/
Admin
A fullstack MCP framework for building MCP Servers and MCP Apps in TypeScript and Python with...
Tokens:333,171
Snippets:4,275
Trust Score:7.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run mcp-use start examples

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Common usage patterns for the start command with various flags.

```bash
mcp-use start
mcp-use start --port 8080
mcp-use start --host 0.0.0.0
mcp-use start --with-inspector
mcp-use start --path ./my-server
mcp-use start --tunnel
```

--------------------------------

### Run Notifications Example

Source: https://docs.mcp-use.com/v2/typescript/server/subscriptions

Commands to start the development server for testing live listener subscriptions.

```bash
cd libraries/typescript/packages/server/examples/notifications
pnpm dev
```

--------------------------------

### Complete File Manager Server Example with Client Roots

Source: https://docs.mcp-use.com/python/client/roots

Demonstrates a full client setup exposing workspace and configuration directories to a file management server. Includes client initialization, session creation, and calling a server tool. Ensure asyncio and necessary MCP types are imported.

```Python
import asyncio
from mcp.types import Root
from mcp_use.client import MCPClient

async def main():
    # Expose workspace directories to the server
    roots = [
        Root(uri="file:///home/user/workspace", name="Workspace"),
        Root(uri="file:///home/user/config", name="Config Files"),
    ]

    config = {
        "mcpServers": {
            "file-manager": {"url": "http://localhost:8000/mcp"}
        }
    }

    client = MCPClient(config, roots=roots)

    try:
        await client.create_all_sessions()
        session = client.get_session("file-manager")

        # The server can now query available roots
        # and operate on files within them
        result = await session.call_tool("list_files", {})
        print(result.content[0].text)

    finally:
        await client.close_all_sessions()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Complete Server Manager Example

Source: https://docs.mcp-use.com/python/agent/server-manager

Demonstrates a full agent setup with a multi-server configuration and a complex task involving various tools. Use this to see the Server Manager in action with multiple MCP servers.

```Python
import asyncio
from mcp_use import MCPClient, MCPAgent
from langchain_openai import ChatOpenAI

async def demo_server_manager():
    # Multi-server configuration
    client = MCPClient.from_dict({
        "mcpServers": {
            "web": {"command": "npx", "args": ["@playwright/mcp@latest"]},
            "files": {"command": "uvx", "args": ["mcp-server-filesystem", "/tmp"]},
            "database": {"command": "uvx", "args": ["mcp-server-sqlite"]}
        }
    })

    # Agent with Server Manager
    agent = MCPAgent(
        llm=ChatOpenAI(model="gpt-4"),
        client=client,
        use_server_manager=True,
        verbose=True  # See the magic happen!
    )

    # Complex multi-server task
    result = await agent.run("""
    I need to build a complete data collection system:

    1. First, show me what servers and tools are available
    2. Scrape product information from https://example-store.com
    3. Clean and structure the data
    4. Save it as both JSON and CSV files
    5. Load the data into a SQLite database
    6. Generate a summary report

    Guide me through each step and show me how you discover and use the right tools.
    """)

    print("Task completed!")
    print(result)

    await agent.close()

if __name__ == "__main__":
    asyncio.run(demo_server_manager())

```

--------------------------------

### Run and test the elicitation example

Source: https://docs.mcp-use.com/v2/typescript/server/elicitation

Commands to start the development server for testing elicitation flows.

```bash
cd libraries/typescript/packages/server/examples/elicitation
pnpm dev
```

--------------------------------

### Test sampling locally with pnpm

Source: https://docs.mcp-use.com/typescript/server/sampling

Commands to navigate to the sampling example directory, install dependencies, and start the development server.

```bash
cd libraries/typescript/packages/mcp-use/examples/server/features/sampling
pnpm install
pnpm dev
```

--------------------------------

### Build command examples

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Examples of running the build command with various options.

```bash
mcp-use build
mcp-use build --inline
mcp-use build --mcp-dir src/mcp
mcp-use build --entry src/server.ts --views-dir src/views
mcp-use build --path ./my-server
```

--------------------------------

### Google MCP Adapter Integration Example

Source: https://docs.mcp-use.com/python/integration/google

This example shows the full integration flow using the GoogleMCPAdapter. It covers client initialization, adapter creation, tool conversion, and multi-turn tool execution with Google's Gemini SDK. Ensure you have the necessary libraries installed and environment variables configured.

```python
from dotenv import load_dotenv
import asyncio
from mcp import MCPClient, types
from mcp.adapters.google import GoogleMCPAdapter
import google.generativeai as genai

load_dotenv()


async def main():
    config = {
        "mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"], "env": {"DISPLAY": ":1"}}}
    }

    try:
        client = MCPClient(config=config)

        # Creates the adapter for Google's format
        adapter = GoogleMCPAdapter()

        # Convert tools from active connectors to Google's format
        await adapter.create_all(client)

        # List concatenation (if you loaded all tools)
        all_tools = adapter.tools + adapter.resources + adapter.prompts
        google_tools = [types.Tool(function_declarations=all_tools)]

        # If you don't want to create all tools, you can call single functions
        # await adapter.create_tools(client)
        # await adapter.create_resources(client)
        # await adapter.create_prompts(client)

        # Use tools with Google's SDK (not agent in this case)
        gemini = genai.Client()

        messages = [
            types.Content(
                role="user",
                parts=[
                    types.Part.from_text(
                        text="Please search on the internet using browser: 'What time is it in Favignana now!'"
                    )
                ],
            )
        ]
        # Initial request
        response = gemini.models.generate_content(
            model="gemini-flash-lite-latest", contents=messages, config=types.GenerateContentConfig(tools=google_tools)
        )

        if not response.function_calls:
            print("The model didn't do any tool call!")
            return

        # Do multiple tool calls if needed
        while response.function_calls:
            for function_call in response.function_calls:
                function_call_content = response.candidates[0].content

                messages.append(function_call_content)

                tool_name = function_call.name
                arguments = function_call.args

                # Use the adapter's map to get the correct executor
                executor = adapter.tool_executors.get(tool_name)

                if not executor:
                    print(f"Error: Unknown tool '{tool_name}' requested by model.")
                    function_response_content = types.Content(
                        role="tool",
                        parts=[
                            types.Part.from_function_response(
                                name=tool_name,
                                response={"error": "No executor found for the tool requested"},
                            )
                        ],
                    )
                else:
                    try:
                        # Execute the tool using the retrieved function
                        print(f"Executing tool: {tool_name}({arguments})")
                        tool_result = await executor(**arguments)

                        # Use the adapter's universal parser
                        content = adapter.parse_result(tool_result)
                        function_response = {"result": content}

                        # Build function response message
                        function_response_part = types.Part.from_function_response(
                            name=tool_name,
                            response=function_response,
                        )
                        function_response_content = types.Content(role="tool", parts=[function_response_part])
                    except Exception as e:
                        print(f"An unexpected error occurred while executing tool {tool_name}: {e}")
                        function_response_content = types.Content(
                            role="tool",
                            parts=[
                                types.Part.from_function_response(
                                    name=tool_name,
                                    response={"error": str(e)},
                                )
                            ],
                        )
                # Append the tool's result to the conversation history
                messages.append(function_response_content)
                # Send the tool's result back to the model to get the next response

            response = gemini.models.generate_content(
                model="gemini-flash-lite-latest",
                contents=messages,
                config=types.GenerateContentConfig(tools=google_tools),
            )

        # Get final response, the loop has finished
        print("\n--- Final response from the model ---")
        if response.text:
            print(response.text)
        else:
            print("The model did not return a final text response.")
            print(response)

        gemini.close()
    except Exception as e:
        print(f"Error: {e}")
        raise e


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Install client and agent packages

Source: https://docs.mcp-use.com/v2/typescript/client/migration

Install the core client and agent packages for v2.

```bash
npm install @mcp-use/client @mcp-use/agent
```

--------------------------------

### Build and start with Inspector

Source: https://docs.mcp-use.com/inspector/integration

Commands to build the project and start the server with the Inspector enabled.

```bash
mcp-use build
mcp-use start --with-inspector
```

--------------------------------

### Quick Start: Bearer Token Authentication Setup

Source: https://docs.mcp-use.com/python/server/auth/bearer

Implement a custom BearerAuthProvider to verify tokens and integrate it with your MCPServer. This example shows how to define API keys and access user claims within a tool.

```python
from mcp_use.server import MCPServer
from mcp_use.server.auth import BearerAuthProvider, AccessToken, get_access_token

API_KEYS = {
    "sk-abc123": {"email": "alice@example.com"},
    "sk-def456": {"email": "bob@example.com"},
}


class MyAuthProvider(BearerAuthProvider):
    async def verify_token(self, token: str) -> AccessToken | None:
        if token not in API_KEYS:
            return None
        return AccessToken(token=token, claims=API_KEYS[token])


server = MCPServer(name="my-server", auth=MyAuthProvider())


@server.tool()
def whoami() -> str:
    """Get current user info."""
    token = get_access_token()
    return f"Hello {token.claims.get('email')}" if token else "Not authenticated"
```

--------------------------------

### Basic MCPAgent Configuration

Source: https://docs.mcp-use.com/python/agent/agent-configuration

Illustrates the basic setup for creating an MCPAgent instance with essential parameters like the language model and client configuration. This is a starting point for agent initialization.

```python
from mcp_use import MCPAgent, MCPClient
from langchain_openai import ChatOpenAI

# Basic configuration
agent = MCPAgent(
    llm=ChatOpenAI(model="gpt-5.5", temperature=0.7),
    client=MCPClient.from_config_file("config.json"),
    max_steps=30
)
```

--------------------------------

### Install MCP-Use CLI

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Commands for installing the framework or the CLI package specifically.

```bash
npm install mcp-use
```

```bash
npm install -g @mcp-use/cli
```

```bash
npx @mcp-use/cli dev
```

```bash
npm install --save-dev @mcp-use/cli
```

--------------------------------

### Combined Server Configuration Example

Source: https://docs.mcp-use.com/python/server/logging

Configure an MCPServer with various settings including debug mode, log filtering, and pretty-printed JSON-RPC. This snippet shows how to initialize the server and start it with a specific transport.

```python
server = MCPServer(
    name="my-server",
    debug=True,
    show_inspector_logs=False,    # Hide inspector noise
    mcp_logs_only=True,           # Only show MCP protocol logs
    pretty_print_jsonrpc=True,    # Pretty-printed JSON-RPC panels
)
server.run(transport="streamable-http")
```

--------------------------------

### Start Documentation Development Server

Source: https://docs.mcp-use.com/python/development/development

Navigate to the docs directory and start the Mintlify development server to preview documentation changes locally.

```bash
cd ../../docs
mintlify dev
```

--------------------------------

### Complete LangChain Integration Example

Source: https://docs.mcp-use.com/python/integration/langchain

A complete, runnable Python script demonstrating the integration of mcp-use with LangChain, including all necessary imports and setup.

```python
import asyncio
from dataclasses import dataclass

from dotenv import load_dotenv
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model

from mcp_use import MCPClient
from mcp_use.agents.adapters import LangChainAdapter

```

--------------------------------

### Run the OpenAPI example

Source: https://docs.mcp-use.com/v2/typescript/server/openapi

Executes the maintained example project using the local development environment.

```bash
cd libraries/typescript/packages/server/examples/openapi
pnpm dev
```

--------------------------------

### install_dependencies(target_dir: pathlib.Path)

Source: https://docs.mcp-use.com/python/api-reference/mcp_use_server_templates_cli

Prompts the user to install dependencies and executes the installer.

```APIDOC
## install_dependencies

### Description
Prompt user to install dependencies and run the installer. Returns True if installed.

### Signature
`def install_dependencies(target_dir: pathlib.Path)`

### Parameters
- **target_dir** (pathlib.Path) - Required - Parameter value

### Returns
- **bool** - Returns True if installed.
```

--------------------------------

### Install mcp-use packages

Source: https://docs.mcp-use.com/typescript/api-reference/overview

Install the core SDK and associated client and agent packages via npm.

```bash
npm install mcp-use @mcp-use/client @mcp-use/agent
```

--------------------------------

### Install React Dependencies

Source: https://docs.mcp-use.com/typescript/client/environments

Command to install the client and React-specific packages.

```bash
npm install @mcp-use/client react
```

--------------------------------

### Install Redis client

Source: https://docs.mcp-use.com/typescript/server/session-management/redis-storage

Install the required redis package to enable Redis support.

```bash
npm install redis
```

--------------------------------

### Install LangChain SDK

Source: https://docs.mcp-use.com/python/integration/langchain

Install the LangChain SDK using pip. This is a prerequisite for using the adapter.

```bash
uv pip install langchain
```

--------------------------------

### Quick start Docker command

Source: https://docs.mcp-use.com/inspector/self-hosting

Starts the Inspector container bound to the local loopback interface.

```bash
docker run -d -p 127.0.0.1:8080:8080 --name mcp-inspector mcpuse/inspector:latest
```

--------------------------------

### Run Development Server

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Syntax for starting the development server.

```bash
mcp-use dev [options]
```

--------------------------------

### Install mcp-use CLI

Source: https://docs.mcp-use.com/typescript/server/deployment/mcp-use

Install the mcp-use CLI globally to manage deployments for projects not created via create-mcp-use-app.

```bash
npm install -g mcp-use
```

--------------------------------

### Install mcp-use with uv

Source: https://docs.mcp-use.com/python/getting-started/quickstart

Install the mcp-use library and a LangChain LLM provider package using uv.

```bash
uv add mcp-use langchain-openai
```

--------------------------------

### Example Inspector links

Source: https://docs.mcp-use.com/inspector/url-parameters

Complete URL examples for connecting to servers and navigating to specific tabs.

```text
https://inspector.mcp-use.com/inspect?autoConnect=https://your-server.com/mcp
```

```text
https://inspector.mcp-use.com/inspect?server=https://your-server.com/mcp&tab=tools
```

--------------------------------

### Preview Documentation

Source: https://docs.mcp-use.com/python/development

Starts the local development server for rendering documentation.

```bash
cd ../../docs
mintlify dev
```

--------------------------------

### mcp-use start

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Runs the production server from the .mcp-use/build/ directory.

```APIDOC
## CLI Command: mcp-use start

### Description
Runs the production server previously written to the .mcp-use/build/ directory. This command requires a valid build manifest and sets the environment to production.

### Syntax
`mcp-use start [options]`

### Options
- **--path** (string) - Optional - Project root containing .mcp-use/build/. Defaults to current directory.
- **--port** (number) - Optional - Server port. Defaults to PORT environment variable, server config, or 3000.
- **--host** (string) - Optional - Bind address. Defaults to HOST environment variable, server config, or 127.0.0.1.
- **--with-inspector** (boolean) - Optional - Mounts the bundled Inspector at ${basePath}/inspector.
- **--tunnel** (boolean) - Optional - Creates a public tunnel for the production server.

### Usage Examples
`mcp-use start`
`mcp-use start --port 8080`
`mcp-use start --host 0.0.0.0`
`mcp-use start --with-inspector`
`mcp-use start --tunnel`
```

--------------------------------

### Get Package Version

Source: https://docs.mcp-use.com/typescript/api-reference/agent/mcp-agent

Returns the installed mcp-use package version.

```ts
static getPackageVersion(): string
```

--------------------------------

### Install Google GenAI SDK

Source: https://docs.mcp-use.com/python/integration/google

Install the Google GenAI SDK using pip. This is a prerequisite for using the adapter.

```bash
uv pip install google-genai
```

--------------------------------

### Complete Google SDK Integration Example

Source: https://docs.mcp-use.com/python/integration/google

This Python script provides a full, runnable example of integrating MCP-Use with the Google SDK. It shows how to use integration adapters for MCP tools and format conversion.

```python
import asyncio

from dotenv import load_dotenv
from google import genai
from google.genai import types

from mcp_use import MCPClient
from mcp_use.agents.adapters import GoogleMCPAdapter

# This example demonstrates how to use our integration
# adapters to use MCP tools and convert to the right format.

```

--------------------------------

### Basic Direct Tool Call Example

Source: https://docs.mcp-use.com/python/client/direct-tool-calls

Demonstrates how to configure MCPClient, create sessions, list tools, and call a specific tool with arguments. Ensure the MCP server is configured and sessions are initialized before calling tools.

```Python
import asyncio
from mcp_use import MCPClient

async def call_tool_example():
    # Configure the MCP server
    config = {
        "mcpServers": {
            "everything": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-everything"],
            }
        }
    }

    # Create client from configuration
    client = MCPClient(config)

    try:
        # Initialize all configured sessions
        await client.create_all_sessions()

        # Get the session for a specific server
        session = client.get_session("everything")

        # List available tools
        tools = await session.list_tools()
        tool_names = [t.name for t in tools]
        print(f"Available tools: {tool_names}")

        # Call a specific tool with arguments
        result = await session.call_tool(
            name="add",
            arguments={"a": 1, "b": 2}
        )

        # Handle the result
        if getattr(result, "isError", False):
            print(f"Error: {result.content}")
        else:
            print(f"Tool result: {result.content}")
            print(f"Text result: {result.content[0].text}")

    finally:
        # Clean up resources
        await client.close_all_sessions()

if __name__ == "__main__":
    asyncio.run(call_tool_example())

```

--------------------------------

### Tunnel Startup Output

Source: https://docs.mcp-use.com/tunneling

Example output showing the local and public endpoints after starting the tunnel.

```text
[mcp-use] starting tunnel for port 3000…
mcp-use server running at http://localhost:3000/mcp
mcp-use public MCP URL: https://proper-black.tunnel.mcp-use.run/mcp
```

--------------------------------

### Quick Start: Custom Middleware Example

Source: https://docs.mcp-use.com/python/client/middleware

Implement a custom middleware by subclassing `Middleware` and overriding specific hooks like `on_call_tool`. This example logs the tool name before calling the next middleware.

```python
from mcp.types import CallToolRequestParams
from mcp_use import MCPClient
from mcp_use.middleware import Middleware, MiddlewareContext, NextFunctionT

class CustomMiddleware(Middleware):
    async def on_call_tool(
        self, context: MiddlewareContext[CallToolRequestParams], call_next: NextFunctionT
    ) -> CallToolResult:
        print(f"Calling tool {context.params.name}")
        return await call_next(context)

config = {
    "mcpServers": {
        "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"], "env": {"DISPLAY": ":1"}}
    }
}

# MCPClient automatically prepends a default logging middleware.
# You can add your own middlewares after it.
client = MCPClient(config=config, middleware=[CustomMiddleware()])
```

--------------------------------

### Test elicitation locally

Source: https://docs.mcp-use.com/typescript/server/elicitation

Commands to install dependencies and start the development server for testing elicitation features.

```bash
cd libraries/typescript/packages/mcp-use/examples/server/features/elicitation
pnpm install
pnpm dev
```

--------------------------------

### Install mcp-use library

Source: https://docs.mcp-use.com/typescript/getting-started/installation

Add the mcp-use package to your project to build an MCP server from scratch.

```bash
npm install mcp-use
```

```bash
pnpm add mcp-use
```

```bash
bun add mcp-use
```

--------------------------------

### Initialize and Run a Minimal MCPServer

Source: https://docs.mcp-use.com/typescript/api-reference/server/mcp-server

Demonstrates creating a server instance, registering a tool, and starting the server listener.

```ts
import { MCPServer, text } from "mcp-use/server";

const server = new MCPServer({
  name: "simple-example-server",
  version: "1.0.0",
  description: "A simple MCP server example",
});

server.tool(
  {
    name: "hello-world",
    description: "A simple tool that returns hello world",
  },
  async () => text("Hello World!")
);

// Start the server (MCP endpoints auto-mounted at /mcp)
await server.listen();
```

--------------------------------

### Initialize MCPClient with Configuration

Source: https://docs.mcp-use.com/python/client/client-configuration

Demonstrates initializing MCPClient using either a configuration file path or a dictionary. It also shows how to create sessions, list tools, and close sessions.

```python
from mcp_use import MCPClient

# From config file
client = MCPClient("config.json")

# From dictionary
client = MCPClient({
    "mcpServers": {
        "playwright": {
            "command": "npx",
            "args": ["@playwright/mcp@latest"]
        }
    }
})

# Create sessions and use
await client.create_all_sessions()
session = client.get_session("playwright")
tools = await session.list_tools()

# Clean up when done
await client.close_all_sessions()
```

--------------------------------

### Create and Use MCP Client

Source: https://docs.mcp-use.com/python/getting-started/quickstart

Demonstrates creating an MCPClient, initializing sessions, listing tools, calling a tool, and cleaning up.

```python
import asyncio
from mcp_use import MCPClient

async def main():
    client = MCPClient({
        "mcpServers": {
            "everything": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-everything"]
            }
        }
    })

    # Initialize all configured sessions
    await client.create_all_sessions()

    # Get the session for a specific server
    session = client.get_session("everything")

    # List available tools
    tools = await session.list_tools()
    print(f"Available tools: {[t.name for t in tools]}")

    # Call a specific tool with arguments
    result = await session.call_tool("add", {"a": 1, "b": 2})
    print(f"Result: {result}")

    # Clean up
    await client.close_all_sessions()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Python Prometheus Metrics for Monitoring

Source: https://docs.mcp-use.com/python/development/security

Defines Prometheus metrics (Counter, Histogram) for tracking requests, durations, and security violations. Ensure Prometheus client library is installed and metrics server is started.

```python
from prometheus_client import Counter, Histogram, start_http_server
import time

# Metrics
REQUEST_COUNT = Counter('mcp_requests_total', 'Total requests', ['user_id', 'status'])
REQUEST_DURATION = Histogram('mcp_request_duration_seconds', 'Request duration')
SECURITY_VIOLATIONS = Counter('mcp_security_violations_total', 'Security violations', ['type'])

async def monitored_agent_execution(user_id: str, query: str):
    start_time = time.time()

    try:
        # Your existing security checks
        is_valid, error = validator.validate_query(query)
        if not is_valid:
            SECURITY_VIOLATIONS.labels(type='invalid_query').inc()
            raise ValueError(error)

        allowed, message = rate_limiter.is_allowed(user_id)
        if not allowed:
            SECURITY_VIOLATIONS.labels(type='rate_limit').inc()
            raise ValueError(message)

        # Execute agent
        agent = await create_secure_agent()
        result = await agent.run(query)

        REQUEST_COUNT.labels(user_id=user_id, status='success').inc()
        return result

    except Exception as e:
        REQUEST_COUNT.labels(user_id=user_id, status='error').inc()
        raise
    finally:
        REQUEST_DURATION.observe(time.time() - start_time)

# Start metrics server
start_http_server(8000)
```

--------------------------------

### Start the development server

Source: https://docs.mcp-use.com/typescript/getting-started/quickstart

Commands to navigate to the project directory and initiate the development server.

```bash
cd my-server
npm run dev
```

--------------------------------

### Quick Start with MCP Client

Source: https://docs.mcp-use.com/v2/typescript/client/index

Initialize the client, connect to a server, and execute a tool.

```typescript
import { MCPClient } from "@mcp-use/client";

const client = new MCPClient({
  mcpServers: {
    demo: { url: "http://localhost:3000/mcp" },
  },
});

try {
  const connection = await client.connect("demo");

  const tools = await connection.listTools();
  console.log(tools.map((tool) => tool.name));

  const result = await connection.callTool("echo", { message: "hello" });
  const text = result.content.find((block) => block.type === "text");
  if (text?.type === "text") {
    console.log(text.text);
  }
} finally {
  await client.close();
}
```

--------------------------------

### Basic Structured Output Example

Source: https://docs.mcp-use.com/python/agent/structured-output

Demonstrates how to use MCPAgent to get structured output in the form of a Pydantic model. The agent will automatically retry to gather missing information until all required fields are populated.

```Python
import asyncio
from pydantic import BaseModel, Field
from langchain_openai import ChatOpenAI
from mcp_use import MCPAgent, MCPClient

class WeatherInfo(BaseModel):
    """Weather information for a location"""
    city: str = Field(description="City name")
    temperature: float = Field(description="Temperature in Celsius")
    condition: str = Field(description="Weather condition")
    humidity: int = Field(description="Humidity percentage")

async def main():
    # Setup client and agent
    client = MCPClient(config={"mcpServers": {...}})
    llm = ChatOpenAI(model="gpt-5.5")
    agent = MCPAgent(llm=llm, client=client)

    # Get structured output
    weather: WeatherInfo = await agent.run(
        "Get the current weather in San Francisco",
        output_schema=WeatherInfo
    )

    print(f"Temperature in {weather.city}: {weather.temperature}°C")
    print(f"Condition: {weather.condition}")
    print(f"Humidity: {weather.humidity}%")

asyncio.run(main())
```

--------------------------------

### Run mcp-use start syntax

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Basic syntax for executing the production server.

```bash
mcp-use start [options]
```

--------------------------------

### run_install(name: str, cmd: list[str], target_dir: pathlib.Path)

Source: https://docs.mcp-use.com/python/api-reference/mcp_use_server_templates_cli

Executes an installation command and captures the output.

```APIDOC
## run_install

### Description
Run the installer, capturing output. Returns True on success.

### Signature
`def run_install(name: str, cmd: list[str], target_dir: pathlib.Path)`

### Parameters
- **name** (str) - Required - Name identifier
- **cmd** (list[str]) - Required - List of items
- **target_dir** (pathlib.Path) - Required - Parameter value

### Returns
- **bool** - Returns True on success.
```

--------------------------------

### Complete Anthropic SDK Integration with MCP

Source: https://docs.mcp-use.com/python/integration/anthropic

This example shows the full integration flow, including setting up the MCP client, creating an AnthropicMCPAdapter, converting tools, and using them with the Anthropic messages API. It handles tool calls, execution, and processing tool results to get a final model response.

```python
import asyncio

from anthropic import Anthropic
from dotenv import load_dotenv

from mcp_use import MCPClient
from mcp_use.agents.adapters import AnthropicMCPAdapter

# This example demonstrates how to use our integration
# adapters to use MCP tools and convert to the right format.
# In particularly, this example uses the AnthropicMCPAdapter.

load_dotenv()


async def main():
    config = {"mcpServers": {"server": {"url": "http://127.0.0.1:8080/mcp"}}}

    try:
        client = MCPClient(config=config)

        # Creates the adapter for Anthropic's format
        adapter = AnthropicMCPAdapter()

        # Convert tools from active connectors to the Anthropic's format
        await adapter.create_all(client)

        # List concatenation (if you loaded all tools)
        anthropic_tools = adapter.tools + adapter.resources + adapter.prompts

        # If you don't want to create all tools, you can call single functions
        # await adapter.create_tools(client)
        # await adapter.create_resources(client)
        # await adapter.create_prompts(client)

        # Use tools with Anthropic's SDK (not agent in this case)
        anthropic = Anthropic()

        # Initial request
        messages = [{"role": "user", "content": "Please could you give me the assistant prompt? My name is vincenzo"}]
        response = anthropic.messages.create(
            model="claude-opus-4-7", tools=anthropic_tools, max_tokens=1024, messages=messages
        )
        messages.append({"role": response.role, "content": response.content})

        print("Claude wants to use tools:", response.stop_reason == "tool_use")
        print("Number of tool calls:", len([c for c in response.content if c.type == "tool_use"]))

        if response.stop_reason == "tool_use":
            tool_results = []
            for c in response.content:
                if c.type != "tool_use":
                    continue

                tool_name = c.name
                arguments = c.input

                # Use the adapter's map to get the correct executor
                executor = adapter.tool_executors.get(tool_name)

                if not executor:
                    print(f"Error: Unknown tool '{tool_name}' requested by model.")
                    content = f"Error: Tool '{tool_name}' not found."
                else:
                    try:
                        # Execute the tool using the retrieved function
                        print(f"Executing tool: {tool_name}({arguments})")
                        tool_result = await executor(**arguments)

                        # Use the adapter's universal parser
                        content = adapter.parse_result(tool_result)
                    except Exception as e:
                        print(f"An unexpected error occurred while executing tool {tool_name}: {e}")
                        content = f"Error executing tool: {e}"

                # Append the result for this specific tool call
                tool_results.append(
                    {
                        "type": "tool_result",
                        "tool_use_id": c.id,
                        "content": content,
                    }
                )

            if tool_results:
                messages.append(
                    {
                        "role": "user",
                        "content": tool_results,
                    }
                )
                # Get final response
                final_response = anthropic.messages.create(
                    model="claude-opus-4-7", max_tokens=1024, tools=anthropic_tools, messages=messages
                )
                print("\n--- Final response from the model ---")
                print(final_response.content[0].text)
            else:
                final_response = response
                print("\n--- Final response from the model ---")
                if final_response.content:
                    print(final_response.content[0].text)

    except Exception as e:
        print(f"Error: {e}")
        raise e


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### server.listen()

Source: https://docs.mcp-use.com/typescript/api-reference/server/mcp-server

Starts the MCP server to listen for incoming requests.

```APIDOC
## server.listen()

### Description
Starts the server. MCP endpoints are automatically mounted at the `/mcp` path.
```

--------------------------------

### Install Langfuse and Laminar Packages

Source: https://docs.mcp-use.com/python/agent/observability

Install the necessary packages for Langfuse and Laminar observability. Ensure these are installed to avoid 'Package not installed' errors.

```bash
# Install the required packages
pip install langfuse  # For Langfuse
pip install lmnr      # For Laminar
```

--------------------------------

### Import setup_logging

Source: https://docs.mcp-use.com/python/api-reference/mcp_use_server_logging_config

Import the setup_logging function from the mcp_use.server.logging.config module.

```python
from mcp_use.server.logging.config import setup_logging
```

--------------------------------

### Install mcp-use with Pip

Source: https://docs.mcp-use.com/python/getting-started/installation

Use pip to install the mcp-use package. This command installs the core library, providing access to MCPAgent, MCPClient, and MCPServer.

```bash
pip install mcp-use
```

--------------------------------

### Install Development Dependencies

Source: https://docs.mcp-use.com/python/development/development

Install the necessary development dependencies for the Python library using pip. This command installs the package in editable mode with development extras.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Using a Custom Adapter with MCPClient

Source: https://docs.mcp-use.com/python/agent/building-custom-agents

Demonstrates how to initialize the MCPClient, create an instance of your custom adapter, and retrieve tools for use with your agent framework.

```python
from your_module import YourFrameworkAdapter
from mcp_use.client import MCPClient

# Initialize the client
client = MCPClient.from_config_file("config.json")

# Create an adapter instance
adapter = YourFrameworkAdapter()

# Get tools with a single line
tools = await adapter.create_tools(client)

# Use the tools with your framework
agent = your_framework.create_agent(tools=tools)

```

--------------------------------

### Start OAuthCallbackServer

Source: https://docs.mcp-use.com/python/api-reference/mcp_use_client_auth_oauth_callback

Start the server and retrieve the redirect URI.

```python
def start():
```

--------------------------------

### Install Langfuse dependencies

Source: https://docs.mcp-use.com/v2/typescript/agent/langchain/observability

Install the required Langfuse packages for observability.

```bash
npm install langfuse langfuse-langchain
```

--------------------------------

### Initialize MCPServer

Source: https://docs.mcp-use.com/python/server/index

Create a new MCPServer instance with basic configuration like name, version, and instructions.

```python
from mcp_use.server import MCPServer

server = MCPServer(
    name="My Server",
    version="1.0.0",
    instructions="A simple example server"
)
```

--------------------------------

### Install mcp-use dependencies

Source: https://docs.mcp-use.com/typescript/server/nextjs-drop-in

Install the required mcp-use and zod packages.

```bash
pnpm add mcp-use zod
```

--------------------------------

### Quick Start MCP Client

Source: https://docs.mcp-use.com/typescript/client/index

Initialize the client, connect to a server, list available tools, and execute a tool call.

```typescript
import { MCPClient } from "@mcp-use/client";

const client = new MCPClient({
  mcpServers: {
    demo: { url: "http://localhost:3000/mcp" },
  },
});

try {
  const connection = await client.connect("demo");

  const tools = await connection.listTools();
  console.log(tools.map((t) => t.name));

  const result = await connection.callTool("echo", { message: "hello" });
  const text = result.content.find((b) => b.type === "text");
  if (text?.type === "text") console.log(text.text);
} finally {
  await client.close();
}
```

--------------------------------

### Create a Custom Agent with LangChain Adapter

Source: https://docs.mcp-use.com/python/agent/building-custom-agents

This example demonstrates how to initialize an MCP client, create a LangChain adapter, generate LangChain-compatible tools from MCP tools, initialize a language model, and create/run a LangChain agent. Ensure you have a configuration file at 'path/to/config.json'.

```Python
import asyncio
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model

from mcp_use.client import MCPClient
from mcp_use.adapters import LangChainAdapter

async def main():
    # Initialize the MCP client
    client = MCPClient.from_config_file("path/to/config.json")

    # Create adapter instance
    adapter = LangChainAdapter()

    # Get LangChain tools directly from the client with a single line
    tools = await adapter.create_tools(client)

    # Initialize your language model
    model = init_chat_model("gpt-5.5", temperature=0.5)

    # Create the agent
    agent = create_agent(
        model=model,
        tools=tools,
        system_prompt="You are a helpful assistant with access to powerful tools.",
    )

    # Run the agent
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "What can you do?"}]}
    )
    print(result)

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Install Dependencies

Source: https://docs.mcp-use.com/python/development

Installs the required development dependencies for the Python project.

```bash
pip install -e ".[dev]"
```

--------------------------------

### All Logs Enabled Example

Source: https://docs.mcp-use.com/python/server/logging

Example output when all logs are shown (mcp_logs_only=False).

```text
MCP:  127.0.0.1:58478 - "POST /mcp [initialize] HTTP/1.1" 200
INFO: 127.0.0.1:58478 - "POST /mcp HTTP/1.1" 200
MCP:  127.0.0.1:58478 - "POST /mcp [tools/list] HTTP/1.1" 200
INFO: 127.0.0.1:58478 - "POST /mcp HTTP/1.1" 200
INFO: 127.0.0.1:58478 - "GET  /docs HTTP/1.1" 200
```

--------------------------------

### Initialize the MCP App project

Source: https://docs.mcp-use.com/typescript/mcp-apps/quickstart

Use the npx command to scaffold a new project from the template and install dependencies.

```bash
npx create-mcp-use-app my-widget-server --template mcp-apps
cd my-widget-server
npm install
```

--------------------------------

### Install CLI globally

Source: https://docs.mcp-use.com/v2/typescript/api-reference/cli-reference

Installs the CLI package directly for global access.

```bash
npm install -g @mcp-use/cli
```

--------------------------------

### Import display_startup_info

Source: https://docs.mcp-use.com/python/api-reference/mcp_use_server_logging_startup

Import the function from the mcp_use library to enable startup logging.

```python
from mcp_use.server.logging.startup import display_startup_info
```

--------------------------------

### Install Supabase client

Source: https://docs.mcp-use.com/typescript/server/authentication/providers/supabase

Install the required Supabase JavaScript client package.

```bash
npm install @supabase/supabase-js
```

--------------------------------

### Run the development server

Source: https://docs.mcp-use.com/v2/typescript/getting-started/quickstart

Navigate to the project directory and start the development server to host the MCP endpoint and Inspector.

```bash
cd my-mcp-app
npm run dev
```

```bash
cd my-mcp-app
pnpm dev
```

```bash
cd my-mcp-app
bun run dev
```

--------------------------------

### Typecheck command examples

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Examples of running the typecheck command with various options.

```bash
mcp-use typecheck
mcp-use typecheck --entry src/server.ts
mcp-use typecheck -- --project tsconfig.check.json --pretty false
```

--------------------------------

### Local Build and Start Commands

Source: https://docs.mcp-use.com/typescript/server/deployment/mcp-use

Commands to build and run the server locally before deployment.

```bash
mcp-use build
mcp-use start
```

--------------------------------

### Build an MCP server from scratch

Source: https://docs.mcp-use.com/typescript/getting-started/installation

Initialize an MCPServer instance, define tools using Zod schemas, and start the server listener.

```typescript
import { MCPServer } from "mcp-use";
import { z } from "zod";

const server = new MCPServer({
  name: "my-server",
  title: "My Server", // display name
  version: "1.0.0",
  description: "My custom MCP server",
  websiteUrl: "https://mcp-use.com",
  favicon: "favicon.ico",
  icons: [
    {
      src: "icon.svg",
      mimeType: "image/svg+xml",
      sizes: ["512x512"],
    },
  ],
});

// Define a tool
server.tool(
  {
    name: "get_weather",
    description: "Get weather for a city",
    inputSchema: z.object({
      city: z.string().describe("City name"),
    }),
    outputSchema: z.object({
      temperature: z.number(),
      condition: z.string(),
      city: z.string(),
    }),
  },
  async ({ city }) => {
    const weather = { temperature: 72, condition: "sunny", city };
    return {
      content: [{ type: "text", text: JSON.stringify(weather) }],
      structuredContent: weather,
    };
  },
);

// Start the MCP server
server.listen(3000);
```

--------------------------------

### listen(port, options)

Source: https://docs.mcp-use.com/typescript/api-reference/server/mcp-server

Starts the HTTP server, mounting MCP protocol endpoints, widget routes, and OAuth routes.

```APIDOC
## listen(port, options)

### Description
Starts the HTTP server. Mounts MCP protocol endpoints, widget routes, and OAuth routes (if configured), then begins listening.

### Parameters
- **port** (number) - Optional - Port to listen on. Defaults to 3000.
- **options** (ListenOptions) - Optional - Listener settings, including host.

### Returns
- **Promise<{ port: number; url: string }>** - Resolves once the server is listening.
```

--------------------------------

### Install mcp-use dependencies

Source: https://docs.mcp-use.com/home/mcp101

Commands to install the mcp-use framework for Python and TypeScript environments.

```bash
pip install mcp-use
```

```bash
pip install langchain-openai
```

```bash
npm install mcp-use
```

--------------------------------

### CLI Client Usage Examples

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Common commands for connecting to servers, listing resources, and executing tool or prompt actions.

```bash
mcp-use client connect local http://localhost:3000/mcp
mcp-use client list
mcp-use client local tools list
mcp-use client local tools call read_file path=/tmp/test.txt
mcp-use client local resources read "file:///tmp/data.json"
mcp-use client local prompts get greeting name=Alice
mcp-use client local auth status
```

--------------------------------

### Implement a complete agent with structured output

Source: https://docs.mcp-use.com/typescript/agent/structured-output

A full example demonstrating agent initialization, schema definition, and execution with error handling and resource cleanup.

```typescript
import { z } from "zod";
import { MCPAgent } from "@mcp-use/agent";

const ProjectSummary = z.object({
  packageName: z.string().nullable(),
  scripts: z.array(z.string()),
  hasTests: z.boolean(),
  notes: z.string(),
});

type ProjectSummary = z.infer<typeof ProjectSummary>;

async function main() {
  const agent = new MCPAgent({
    llm: "openai/gpt-4o",
    mcpServers: {
      filesystem: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "./"],
      },
    },
  });

  try {
    const summary: ProjectSummary = await agent.run({
      prompt: "Inspect package.json and summarize the project scripts.",
      schema: ProjectSummary,
      maxSteps: 8,
    });

    console.log(summary);
  } finally {
    await agent.close();
  }
}

main().catch(console.error);
```

--------------------------------

### Install @mcp-use/agent

Source: https://docs.mcp-use.com/typescript/agent/index

Install the core agent package using your preferred package manager.

```bash
npm install @mcp-use/agent
```

```bash
pnpm add @mcp-use/agent
```

```bash
bun add @mcp-use/agent
```

--------------------------------

### Install OpenAI SDK

Source: https://docs.mcp-use.com/python/integration/openai

Install the OpenAI SDK using pip before proceeding with the integration.

```bash
uv pip install openai
```

--------------------------------

### Initialize the Main Server

Source: https://docs.mcp-use.com/python/server/router

Register the math router into the main MCPServer instance.

```python
# main.py
from mcp_use.server import MCPServer
from routes.math import router as math_router

server = MCPServer(name="nested-example")
server.include_router(math_router, prefix="math")

server.run(transport="streamable-http")
```

--------------------------------

### Import and Signature for run_install

Source: https://docs.mcp-use.com/python/api-reference/mcp_use_server_templates_cli

Executes an installation command and captures the output.

```python
from mcp_use.server.templates.cli import run_install
```

```python
def run_install(name: str, cmd: list[str], target_dir: pathlib.Path):
```

--------------------------------

### Clerk Provider Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/auth-providers

Example of initializing an MCP server with zero-config Clerk authentication.

```ts
import { MCPServer, oauthClerkProvider, object } from "mcp-use/server";

// Zero-config: reads MCP_USE_OAUTH_CLERK_FRONTEND_API_URL
const server = new MCPServer({
  name: "clerk-oauth-example",
  version: "1.0.0",
  description: "MCP server with Clerk OAuth authentication",
  oauth: oauthClerkProvider(),
});

server.tool(
  {
    name: "get-user-info",
    description: "Get information about the authenticated user",
  },
  async (_args, ctx) =>
    object({
      userId: ctx.auth.user.userId,
      email: ctx.auth.user.email,
      name: ctx.auth.user.name,
    }),
);

server.listen();
```

--------------------------------

### List and call MCP tools

Source: https://docs.mcp-use.com/typescript/client/tools

Demonstrates initializing a client, connecting to a server, listing available tools, and executing a tool call.

```typescript
import { MCPClient } from "@mcp-use/client";

const client = new MCPClient({
  mcpServers: { demo: { url: "http://localhost:3000/mcp" } },
});

try {
  const conn = await client.connect("demo");

  const tools = await conn.listTools();
  for (const tool of tools) {
    console.log(tool.name, tool.description);
  }

  const result = await conn.callTool("read_file", { path: "/tmp/a.txt" });

  if (result.isError) {
    console.error(result.content);
  } else {
    for (const block of result.content) {
      if (block.type === "text") console.log(block.text);
    }
  }
} finally {
  await client.close();
}
```

--------------------------------

### Auth0 Provider Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/auth-providers

Example of initializing an MCP server with zero-config Auth0 authentication.

```ts
import { MCPServer, oauthAuth0Provider, error, object } from "mcp-use/server";

// Zero-config: reads MCP_USE_OAUTH_AUTH0_DOMAIN and MCP_USE_OAUTH_AUTH0_AUDIENCE
const server = new MCPServer({
  name: "auth0-oauth-example",
  version: "1.0.0",
  description: "MCP server with Auth0 OAuth authentication",
  oauth: oauthAuth0Provider(),
});

server.tool(
  {
    name: "get-user-info",
    description: "Get information about the authenticated user",
  },
  async (_args, ctx) =>
    object({
      userId: ctx.auth.user.userId,
      email: ctx.auth.user.email,
      name: ctx.auth.user.name,
      permissions: ctx.auth.permissions,
      scopes: ctx.auth.scopes,
    }),
);

server.listen();
```

--------------------------------

### Resource usage example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Example of using the resource helper within a tool definition.

```ts
import { MCPServer, mix, text, resource } from "mcp-use"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "get-help",
    description: "Return help docs with embedded resource reference",
    schema: z.object({ topic: z.enum(["api", "auth"]) }),
  },
  async ({ topic }) =>
    mix(text(`Help for: ${topic}`), resource(`docs://${topic}`, "text/markdown"))
)
```

--------------------------------

### Audio helper usage example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Example of using the audio helper with base64 data.

```ts
import { MCPServer, audio } from "mcp-use"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "get-audio-sample",
    description: "Return an audio sample",
    schema: z.object({}),
  },
  async () => {
    const base64 = Buffer.from("fake-audio-data").toString("base64")
    return audio(base64, "audio/wav")
  }
)
```
Tokens:
Raw