Skip to main content
MCP Servers allow you to integrate remote tools and capabilities into your ShuttleAI workflows without needing to manually implement or handle the tool logic yourself. Unlike traditional function tools, MCP (Model Context Protocol) connects to external servers that provide and execute the tools remotely, enabling seamless access to data sources, actions, or services. This is an open standard for AI integrations, similar to how Anthropic’s Claude uses MCP for GitHub access or OpenAI’s ChatGPT uses it for features like canvas editing.
While not all models support MCP, the official ShuttleAI model, shuttle-3.5, supports it, including during streaming. When using MCP tools, the chat completions API handles interactions with the remote server automatically, resolving tool calls and incorporating results into the final response without requiring manual intervention from your code.

​
What is an MCP Tool?

MCP, or Model Context Protocol, is an open-source standard introduced by Anthropic for connecting AI models to external systems, tools, and data sources in a secure, standardized way. It acts like a universal interface (often compared to USB-C for AI) that allows models to request and receive context or perform actions via remote servers. An MCP tool in ShuttleAI’s API specifies a connection to an MCP server, which hosts the actual tools (e.g., APIs for data retrieval or computations). The server handles tool discovery, execution, and responses. ShuttleAI provides its own official MCP server at https://mcp.shuttleai.com/mcp, which includes the following self-explanatory tools:
  • chat_completion: For generating chat responses using sub-models or specialized completions.
  • image_generation: For creating images based on prompts.
  • list_models: For retrieving available models.
  • model_analytics: For fetching user-specific model usage statistics (e.g., token counts, API calls).
Authorization for the ShuttleAI MCP server uses your ShuttleAI API key, which can be passed via the Authorization header (Bearer token style) or as a query parameter in the server_url (e.g., https://mcp.shuttleai.com/mcp?api_key=your_key_here).

​
How should an MCP Tool look?

Here’s a basic example of an MCP tool connecting to the official ShuttleAI MCP server. Note that server_url must start with https://, and you can optionally restrict allowed_tools or set require_approval to “never” for automatic execution without model confirmation. 
tools = [
    {
        "type": "mcp",
        "server_label": "ShuttleAI MCP",
        "server_url": "https://mcp.shuttleai.com/mcp",
        "allowed_tools": ["model_analytics"],  # Optional: Restrict to specific tools
        "require_approval": "always",  # Default; use "never" for no approval step
        "headers": {
            "authorization": "Bearer your_shuttleai_api_key_here"
        }
    }
]
Alternatively, if you prefer not to use headers, include the API key in the URL: 
tools = [
    {
        "type": "mcp",
        "server_label": "ShuttleAI MCP",
        "server_url": "https://mcp.shuttleai.com/mcp?api_key=your_shuttleai_api_key_here",
        "allowed_tools": ["model_analytics"]
    }
]
You can mix MCP tools with function tools in the same tools array for hybrid setups.

​
Example Usage

Let’s use the model_analytics tool as an example. This tool retrieves your model usage stats from the ShuttleAI MCP server. First, set up the tools as above. Then, make a chat completions request: 
curl https://api.shuttleai.com/v1/chat/completions \
  -H "Authorization: Bearer $SHUTTLEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shuttle-3.5",
    "messages": [{"role": "user", "content": "What are my token usage stats right now?"}],
    "tools": [
      {
        "type": "mcp",
        "server_label": "ShuttleAI MCP",
        "server_url": "https://mcp.shuttleai.com/mcp?api_key=$SHUTTLEAI_API_KEY"
      }
    ]
  }'
Since MCP handling is automatic, the API will interact with the remote server (e.g., calling model_analytics if the model deems it necessary), process the results, and return a final completion. A sample response might look like this (actual stats depend on your usage): 
{
  "id": "chatcmpl-example-id",
  "object": "chat.completion",
  "created": 1730230592,
  "model": "shuttle-3.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Your model usage stats: Total prompt tokens: 1500, completion tokens: 800, API calls: 25."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 60,
    "completion_tokens": 40,
    "total_tokens": 100,
    "completion_tokens_details": {
        "reasoning_tokens": 0
    }
  }
}
No manual parsing or execution is needed—the remote MCP server provides the stats directly, and the model incorporates them into the response.
ShuttleAI supports parallel MCP tool calls and streaming with MCP for efficient, real-time integrations!
For more examples, check out our GitHub