> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shuttleai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Servers

> Connect AI models to external tools and services using the Model Context Protocol.

The **Model Context Protocol (MCP)** lets you connect AI models to external tool servers. Instead of defining tools inline, you point the model at an MCP server URL and it discovers and uses the available tools automatically.

## How MCP works

1. You provide an MCP server URL in the `tools` array
2. The model connects to the server and discovers available tools
3. The model calls tools as needed to fulfill the request
4. Results are incorporated into the final response

## Using an MCP server

Add an MCP tool type to your request:

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="shuttle-xxx",
    base_url="https://api.shuttleai.com/v1"
)

response = client.chat.completions.create(
    model="shuttleai/auto",
    messages=[{"role": "user", "content": "List all available models"}],
    tools=[
        {
            "type": "mcp",
            "server_url": "https://mcp.shuttleai.com/mcp",
            "server_label": "ShuttleAI MCP",
            "require_approval": "never"
        }
    ]
)

print(response.choices[0].message.content)
```

## MCP tool parameters

| Parameter          | Type      | Required | Description                              |
| ------------------ | --------- | -------- | ---------------------------------------- |
| `type`             | string    | Yes      | Must be `"mcp"`                          |
| `server_url`       | string    | Yes      | URL of the MCP server                    |
| `server_label`     | string    | No       | Human-readable label for the server      |
| `allowed_tools`    | string\[] | No       | Restrict which tools the model can use   |
| `require_approval` | string    | No       | `"never"` to auto-approve tool calls     |
| `headers`          | object    | No       | Custom headers to send to the MCP server |

## ShuttleAI's official MCP server

We provide an official MCP server at:

```
https://mcp.shuttleai.com/mcp
```

Available tools on the official server:

| Tool              | Description               |
| ----------------- | ------------------------- |
| `chat_completion` | Generate text completions |
| `list_models`     | List available models     |
| `model_analytics` | Get model usage analytics |

### Authentication

Pass your API key to the MCP server via headers:

```python theme={null}
response = client.chat.completions.create(
    model="shuttleai/auto",
    messages=[{"role": "user", "content": "List all available models"}],
    tools=[
        {
            "type": "mcp",
            "server_url": "https://mcp.shuttleai.com/mcp",
            "server_label": "ShuttleAI",
            "require_approval": "never",
            "headers": {
                "Authorization": "Bearer shuttle-xxx"
            }
        }
    ]
)
```

## Filtering tools

Use `allowed_tools` to restrict which tools the model can access:

```python theme={null}
tools=[
    {
        "type": "mcp",
        "server_url": "https://mcp.shuttleai.com/mcp",
        "allowed_tools": ["list_models", "chat_completion"],
        "require_approval": "never"
    }
]
```

## Combining MCP with function tools

You can use MCP tools alongside regular function tools in the same request:

```python theme={null}
tools = [
    # Regular function tool
    {
        "type": "function",
        "function": {
            "name": "get_user_data",
            "description": "Get data for the current user",
            "parameters": {"type": "object", "properties": {}}
        }
    },
    # MCP tool
    {
        "type": "mcp",
        "server_url": "https://mcp.shuttleai.com/mcp",
        "require_approval": "never"
    }
]
```

## Building your own MCP server

Any server that implements the [Model Context Protocol](https://modelcontextprotocol.io/) specification can be used with ShuttleAI. This lets you give AI models access to your own internal tools, databases, and APIs.