FastAPI MCP

https://github.com/tadata-org/fastapi_mcp
Admin
Expose your FastAPI endpoints as Model Context Protocol (MCP) tools with built-in authentication and...
Tokens:12,914
Snippets:117
Trust Score:7
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install FastAPI-MCP with uv

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/getting-started/installation.mdx

Recommended installation method using uv, a fast Python package installer.

```bash
uv add fastapi-mcp
```

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

### Install FastAPI-MCP with uv pip or pip

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/getting-started/installation.mdx

Alternative installation methods using uv pip or pip.

```bash
uv pip install fastapi-mcp
```

```bash
pip install fastapi-mcp
```

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

### Install and run pre-commit hooks

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/CONTRIBUTING.md

Installs and runs pre-commit hooks. These hooks automatically run checks like ruff and formatting on each commit.

```bash
uv run pre-commit install
uv run pre-commit run
```

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

### Start MCP Inspector with npx

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/getting-started/FAQ.mdx

Run this command in a new terminal to start the MCP Inspector, which is used to verify that your FastApiMCP server is working. After starting your FastAPI application, connect to the MCP server by entering the mount path URL (default: http://127.0.0.1:8000/mcp).

```bash
npx @modelcontextprotocol/inspector
```

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

### FastApiMCP with AuthConfig and setup_proxies=True

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/auth.mdx

Configures FastApiMCP with OAuth provider details and proxy setup. setup_proxies=True creates compatibility proxies for MCP clients. Ensure callback URLs are configured correctly in the OAuth provider.

```python
mcp = FastApiMCP(
    app,
    auth_config=AuthConfig(
        # Your OAuth provider information
        issuer="https://auth.example.com",
        authorize_url="https://auth.example.com/authorize",
        oauth_metadata_url="https://auth.example.com/.well-known/oauth-authorization-server",

        # Credentials registered with your OAuth provider
        client_id="your-client-id",
        client_secret="your-client-secret",

        # Recommended, since some clients don't specify them
        audience="your-api-audience",
        default_scope="openid profile email",

        # Your auth checking dependency
        dependencies=[Depends(verify_auth)],

        # Create compatibility proxies - usually needed!
        setup_proxies=True,
    ),
)
```

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

### Auth0 environment variables (.env)

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/auth.mdx

Required environment variables for the Auth0 example. Set these in a .env file in the project root.

```plaintext
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=https://your-tenant.auth0.com/api/v2/
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
```

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

### Mount FastAPI-MCP server

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/getting-started/welcome.mdx

Minimal setup to expose FastAPI endpoints as MCP tools. Requires a FastAPI app instance and mounts the MCP server at /mcp.

```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

mcp = FastApiMCP(app)
mcp.mount_http()
```

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

### Enable describe_all_responses and describe_full_response_schema flags

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/configurations/customization.mdx

Set both flags to True when creating the MCP server to include all possible response schemas and full JSON schema in tool descriptions. This example shows the configuration with both flags enabled.

```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

mcp = FastApiMCP(
    app,
    name="My API MCP",
    description="Very cool MCP server",
    describe_all_responses=True,
    describe_full_response_schema=True
)

mcp.mount_http()
```

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

### Configure FastAPI-MCP with custom httpx.AsyncClient

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/asgi.mdx

Use this snippet to configure FastAPI-MCP with a custom HTTP client, overriding the default ASGI transport. The custom client specifies a base URL and timeout, which is useful when the FastAPI server is not running locally or when a different transport is needed. The example highlights the custom client creation and its use in the FastApiMCP constructor.

```python
import httpx
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

custom_client = httpx.AsyncClient(
    base_url="https://api.example.com",
    timeout=30.0
)

mcp = FastApiMCP(
    app,
    http_client=custom_client
)

mcp.mount()
```

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

### OAuth Flow with FastApiMCP and mcp-remote

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/auth.mdx

Configure FastApiMCP with AuthConfig to enable OAuth 2 flow, then call it using mcp-remote with a fixed port. The JSON config shows the client setup for MCP clients.

```python
from fastapi import Depends
from fastapi_mcp import FastApiMCP, AuthConfig

mcp = FastApiMCP(
    app,
    name="MCP With OAuth",
    auth_config=AuthConfig(
        issuer=f"https://auth.example.com/",
        authorize_url=f"https://auth.example.com/authorize",
        oauth_metadata_url=f"https://auth.example.com/.well-known/oauth-authorization-server",
        audience="my-audience",
        client_id="my-client-id",
        client_secret="my-client-secret",
        dependencies=[Depends(verify_auth)],
        setup_proxies=True,
    ),
)

mcp.mount_http()
```

```json
{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp",
        "8080"  // Optional port number. Necessary if you want your OAuth to work and you don't have dynamic client registration.
      ]
    }
  }
}
```

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

### Set up development environment with uv sync

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/CONTRIBUTING.md

Creates and uses a virtual environment automatically. Run from the project root after cloning.

```bash
uv sync
```

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

### Create a basic MCP server with FastApiMCP

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/getting-started/quickstart.mdx

Creates a basic MCP server by wrapping a FastAPI app with FastApiMCP and mounting it to the existing application. The highlighted lines (2, 8, 11) show the key steps: importing FastApiMCP, creating the MCP server, and mounting it.

```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# Create (or import) a FastAPI app
app = FastAPI()

# Create an MCP server based on this app
mcp = FastApiMCP(app)

# Mount the MCP server directly to your app
mcp.mount_http()
```

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

### Refresh MCP server with mcp.setup_server() after adding endpoints

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/refresh.mdx

Shows how to add endpoints to a FastAPI app after creating the MCP server and then refresh it with `mcp.setup_server()` to include them. The new endpoint is defined with `@app.get` and the refresh call is placed after the endpoint definition.

```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

mcp = FastApiMCP(app)
mcp.mount_http()

# Add new endpoints after MCP server creation
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
    return {"message": "Hello, world!"}

# Refresh the MCP server to include the new endpoint
mcp.setup_server()
```

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

### Mount MCP server to a separate FastAPI app and run both apps

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/deploy.mdx

Create an MCP server from one FastAPI app and mount it to a separate FastAPI app, then run both apps independently with uvicorn on different hosts and ports.

```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# Your API app
api_app = FastAPI()
# ... define your API endpoints on api_app ...

# A separate app for the MCP server
mcp_app = FastAPI()

# Create MCP server from the API app
mcp = FastApiMCP(api_app)

# Mount the MCP server to the separate app
mcp.mount_http(mcp_app)
```

```bash
uvicorn main:api_app --host api-host --port 8001
uvicorn main:mcp_app --host mcp-host --port 8000
```

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

### Add runtime dependency with uv add

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/CONTRIBUTING.md

Adds a runtime dependency to the project.

```bash
uv add new-package
```

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

### Run commands with virtual environment activated

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/CONTRIBUTING.md

Activates the virtual environment and runs commands directly. On Windows, use .venv\Scripts\activate instead.

```bash
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Then run commands directly
pytest
mypy .
ruff check .
```

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

### Define MCP server metadata

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/configurations/customization.mdx

Sets the MCP server name and description when creating the FastApiMCP instance. The name and description are passed as keyword arguments to the constructor.

```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

mcp = FastApiMCP(
    app,
    name="My API MCP",
    description="Very cool MCP server",
)
mcp.mount_http()
```

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

### Advanced configuration with custom routing for HTTP and SSE

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/transport.mdx

This snippet shows how to configure both transport methods with custom routing and authentication. It mounts the MCP server to a custom path using an APIRouter with a prefix, demonstrating the same FastAPI integration features for both transports.

```python
from fastapi import FastAPI, APIRouter
from fastapi_mcp import FastApiMCP

app = FastAPI()
router = APIRouter(prefix="/api/v1")

mcp = FastApiMCP(app)

# Mount to custom path with HTTP transport
mcp.mount_http(router, mount_path="/my-http")

# Or with SSE transport
mcp.mount_sse(router, mount_path="/my-sse")
```

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

### Run code style and type checks

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/CONTRIBUTING.md

Runs the code quality checks: ruff for linting and formatting, and mypy for type checking.

```bash
# Check code formatting and style
ruff check .
ruff format .

# Check types
mypy .
```

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

### Mount HTTP transport with FastApiMCP

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/transport.mdx

Use this snippet to mount the MCP server using the recommended HTTP transport. The `mount_http()` method implements the latest MCP Streamable HTTP specification, providing better session management and robust connection handling.

```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()
mcp = FastApiMCP(app)

# Mount using HTTP transport (recommended)
mcp.mount_http()
```

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

### Mount SSE transport with FastApiMCP

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/transport.mdx

Use this snippet to mount the MCP server using SSE transport for backwards compatibility with older MCP implementations. The `mount_sse()` method uses Server-Sent Events for communication.

```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()
mcp = FastApiMCP(app)

# Mount using SSE transport (backwards compatibility)
mcp.mount_sse()
```

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

### Run tests with pytest

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/CONTRIBUTING.md

Runs the test suite using pytest.

```bash
# Run all tests
pytest
```

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

### Run the MCP server with uvicorn

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/getting-started/quickstart.mdx

Runs the FastAPI server with uvicorn so the MCP endpoint is served at http://localhost:8000/mcp. The highlighted lines (9-11) show the uvicorn run block. Execute the script with `python fastapi_mcp_server.py`.

```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

mcp = FastApiMCP(app)
mcp.mount_http()

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

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

### Clone fork and add upstream remote

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/CONTRIBUTING.md

Clones your fork of the repository and adds the upstream remote for the original project. Replace YOUR-USERNAME with your GitHub username.

```bash
git clone https://github.com/YOUR-USERNAME/fastapi_mcp.git
cd fastapi-mcp

# Add the upstream remote
git remote add upstream https://github.com/tadata-org/fastapi_mcp.git
```

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

### Commit dependency files

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/CONTRIBUTING.md

Stages and commits the dependency files after adding a new package.

```bash
git add pyproject.toml uv.lock
git commit -m "Add new-package dependency"
```

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

### Add development dependency with uv add --group dev

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/CONTRIBUTING.md

Adds a development dependency (for development, testing, or CI) to the dev group.

```bash
uv add --group dev new-package
```

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

### Add dependency to reject requests without authorization header

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/auth.mdx

Configure FastApiMCP with an AuthConfig that includes a dependency (verify_auth) to reject requests without a valid authorization header. This is optional but recommended for protected endpoints.

```python
from fastapi import Depends
from fastapi_mcp import FastApiMCP, AuthConfig

mcp = FastApiMCP(
    app,
    name="Protected MCP",
    auth_config=AuthConfig(
        dependencies=[Depends(verify_auth)],
    ),
)
mcp.mount_http()
```

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

### Custom OAuth Metadata with AuthConfig

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/auth.mdx

Provide custom OAuth metadata directly via custom_oauth_metadata for full control. Requires mcp-remote on a fixed port (e.g., 8080) and callback URL set to http://127.0.0.1:8080/oauth/callback.

```python
from fastapi import Depends
from fastapi_mcp import FastApiMCP, AuthConfig

mcp = FastApiMCP(
    app,
    name="MCP With Custom OAuth",
    auth_config=AuthConfig(
        # Provide your own complete OAuth metadata
        custom_oauth_metadata={
            "issuer": "https://auth.example.com",
            "authorization_endpoint": "https://auth.example.com/authorize",
            "token_endpoint": "https://auth.example.com/token",
            "registration_endpoint": "https://auth.example.com/register",
            "scopes_supported": ["openid", "profile", "email"],
            "response_types_supported": ["code"],
            "grant_types_supported": ["authorization_code"],
            "token_endpoint_auth_methods_supported": ["none"],
            "code_challenge_methods_supported": ["S256"]
        },

        # Your auth checking dependency
        dependencies=[Depends(verify_auth)],
    ),
)

mcp.mount_http()
```

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

### SSE transport client connection configuration

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/transport.mdx

This JSON configuration shows how MCP clients connect to the SSE transport endpoint. The client uses the same URL but communicates via Server-Sent Events at `http://localhost:8000/sse`.

```json
{
  "mcpServers": {
    "fastapi-mcp": {
      "url": "http://localhost:8000/sse"
    }
  }
}
```

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

### Run commands without activating virtual environment

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/CONTRIBUTING.md

Runs commands without activating the virtual environment by prefixing with uv run.

```bash
# Use uv run prefix for all commands
uv run pytest
uv run mypy .
uv run ruff check .
```

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

### HTTP transport client connection configuration

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/transport.mdx

This JSON configuration shows how MCP clients connect to the HTTP transport endpoint. The client connects directly to the HTTP endpoint at `http://localhost:8000/mcp`.

```json
{
  "mcpServers": {
    "fastapi-mcp": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

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

### Configure MCP client to send authorization header

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/auth.mdx

Set up the MCP client (using npx mcp-remote) to pass an authorization header to your FastAPI endpoints. The header value is read from the environment variable AUTH_HEADER.

```json
{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ]
    },
    "env": {
      "AUTH_HEADER": "Bearer <your-token>"
    }
  }
}
```

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

### mcp-remote fixed port configuration

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/advanced/auth.mdx

JSON configuration for mcp-remote to use a fixed port (8080) so the OAuth provider's callback URL can be configured correctly. The callback URL should be set to http://127.0.0.1:8080/oauth/callback.

```json
{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp",
        "8080"
      ]
    }
  }
}
```

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

### Connect an MCP client via mcp-remote

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/getting-started/quickstart.mdx

Configuration for using mcp-remote as a bridge when the client does not support SSE or when authentication is needed. The optional port number (8080) is required for OAuth to work if dynamic client registration is not available.

```json
{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp",
        "8080"  // Optional port number. Necessary if you want your OAuth to work and you don't have dynamic client registration.
      ]
    }
  }
}
```

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

### FastAPI endpoint with explicit operation_id for MCP tool naming

Source: https://github.com/tadata-org/fastapi_mcp/blob/main/docs/configurations/tool-naming.mdx

Shows two FastAPI endpoint definitions: one with an auto-generated operation_id and one with an explicit operation_id. The explicit operation_id makes the MCP tool name clearer and more intuitive.

```python
# Auto-generated operation_id (something like "read_user_users__user_id__get")
@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

# Explicit operation_id (tool will be named "get_user_info")
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
    return {"user_id": user_id}
```
Tokens:
Raw