---

title: 'Model Context Protocol Tools' sidebar_label: 'MCP Tools'

Spice integrates with tools and services using the Model Context Protocol (MCP). MCP tools can be configured to run internally or connect to external servers over HTTP using the Streamable HTTP transport.

Overview

MCP helps extend the capabilities of the Spice runtime by enabling integration with external tools and services. This includes:

1. Running stdio-based MCP servers internally.
2. Connecting to external MCP servers over Streamable HTTP.

Configuring MCP Tools

To configure MCP tools, define them in the tools section of your spicepod.yaml file. The from field specifies the transport mechanism, such as mcp:npx for stdio-based tools or an HTTP URL for Streamable HTTP-based tools.

Example: Adding an MCP Tool (Stdio)

The following example demonstrates how to configure an MCP tool using npx to run a Google Maps MCP server:

Example: Connecting to an External MCP Server (Streamable HTTP)

This example shows how to connect to an external MCP server over Streamable HTTP:

Example: Connecting to an Auth-Enabled MCP Server (Streamable HTTP)

Streamable HTTP MCP tools support sending an Authorization: Bearer token via mcp_auth_token, or arbitrary HTTP headers via mcp_headers. Both parameters resolve secret references before the MCP client is constructed.

Sending a bearer token:

Sending a custom header (e.g., API key):

If both mcp_auth_token and a custom Authorization header in mcp_headers are set, mcp_auth_token wins and a warning is logged.

Using MCP Tools with Models

Once configured, MCP tools can be assigned to models via the tools parameter. For example:

Spice as an MCP Server

Spice can also act as an MCP server, exposing its tools over Streamable HTTP. This enables other Spice instances or external systems to connect and use the tools.

Example: Connecting to Another Spice Instance via MCP

Allowed Hosts

By default the /v1/mcp endpoint only accepts requests with a Host header matching localhost, 127.0.0.1, or ::1 to prevent DNS rebinding attacks. To allow additional hosts, configure runtime.mcp.allowed_hosts:

Set allowed_hosts: ["*"] to disable host checking entirely.

Configuration Options

from

The from field specifies the transport mechanism for the MCP tool:

• Streamable HTTP: Use an HTTP URL pointing to the MCP endpoint (e.g., http://localhost:8090/v1/mcp).
• Stdio: Use commands like mcp:npx or mcp:docker. Additional arguments can be passed via params.mcp_args.

params

The params field provides additional configuration for MCP tools.

For stdio-based tools, use mcp_args to specify command-line arguments:

For Streamable HTTP tools, the following auth parameters are supported:

• mcp_auth_token — Sends Authorization: Bearer <token> on every request to the MCP server.
• mcp_headers — Sends additional HTTP headers using the same Header: Value comma- or semicolon-delimited format as the HTTP data connector's http_headers. Header values are marked sensitive.

Both parameters support secret expansion. When mcp_auth_token is set, an Authorization header in mcp_headers is ignored and a warning is logged to avoid duplicate auth headers.

env

For stdio-based MCP tools, environment variables can be set using the env field.

description

The description field provides a textual description of the tool. This description is passed to any language model that uses the tool.

For more details, see the MCP Tools Reference.