MCP Configuration Reference

This page provides a complete reference for configuring the MCP client in mistral.rs.

Quick Start - Minimal Configuration

For simple use cases, you can now use a minimal configuration that leverages smart defaults:

{
  "servers": [{
    "name": "Hugging Face MCP Server",
    "source": {
      "type": "Http",
      "url": "https://hf.co/mcp"
    },
    "bearer_token": "hf_xxx"
  }]
}

This automatically provides:

• UUID-based server ID: Unique identifier generated automatically
• Enabled by default: Server is active without explicit enabled: true
• UUID-based tool prefix: Prevents naming conflicts automatically
• No timeouts: Tools and connections don’t timeout by default
• Sequential execution: Only 1 concurrent tool call to prevent overwhelming servers
• Auto-registration: Tools are automatically discovered and registered

Configuration Structure

McpClientConfig

The top-level configuration for the MCP client:

{
  "servers": [...],                    // Array of MCP server configurations
  "auto_register_tools": true,         // Automatically register discovered tools (default: true)
  "tool_timeout_secs": null,           // Timeout for individual tool calls, null = no timeout (default: null)
  "max_concurrent_calls": 1            // Maximum concurrent tool executions (default: 1)
}

McpServerConfig

Configuration for each MCP server:

{
  "id": "unique_id",                  // Unique identifier (default: UUID if not specified)
  "name": "Display Name",             // Human-readable name
  "source": {...},                    // Transport configuration (see below)
  "enabled": true,                    // Enable/disable this server (default: true)
  "tool_prefix": "mcp_abc123",         // Prefix for tool names (default: UUID-based if not specified)
  "resources": ["pattern"],           // Optional resource patterns
  "bearer_token": "token"             // Optional authentication token
}

Transport Source Configuration

HTTP Transport

{
  "type": "Http",
  "url": "https://api.example.com/mcp",
  "timeout_secs": null,               // Optional, null = no timeout (default)
  "headers": {                        // Optional custom headers
    "X-API-Version": "v1",
    "User-Agent": "mistral-rs/0.6.0"
  }
}

WebSocket Transport

{
  "type": "WebSocket", 
  "url": "wss://realtime.example.com/mcp",
  "timeout_secs": null,               // Optional, null = no timeout (default)
  "headers": {                        // Optional WebSocket headers
    "Origin": "https://mistral.rs",
    "Sec-WebSocket-Protocol": "mcp"
  }
}

Process Transport

{
  "type": "Process",
  "command": "mcp-server-filesystem",
  "args": ["--root", "/tmp"],         // Command arguments
  "work_dir": "/home/user",           // Optional working directory
  "env": {                            // Optional environment variables
    "MCP_LOG_LEVEL": "info"
  }
}

Field Reference

McpClientConfig Fields

McpServerConfig Fields

Transport Source Fields

HTTP Source

WebSocket Source

Process Source

Authentication

Bearer Token

The bearer_token field is automatically added as an Authorization: Bearer <token> header for HTTP and WebSocket connections.

{
  "bearer_token": "hf_AbCdEfGhIjKlMnOpQrStUvWxYz"
}

Custom Headers

For other authentication schemes, use the headers field:

{
  "source": {
    "type": "Http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "X-API-Key": "your-api-key",
      "X-Client-ID": "your-client-id"
    }
  }
}

Tool Naming

Without Prefix

Tools are registered with their original names:

• MCP tool: search → Registered as: search

With Prefix

When tool_prefix is set, all tools from that server get prefixed:

• MCP tool: search with prefix web → Registered as: web_search

This prevents conflicts when multiple servers provide tools with the same name.

Resource Patterns

The resources field accepts glob-like patterns:

{
  "resources": [
    "file://**/*.txt",      // All .txt files
    "file://data/**",       // Everything under data/
    "db://users/*",         // All user records
    "api://v1/metrics"      // Specific endpoint
  ]
}

Environment Variables

Using Environment Variables in Configuration

While JSON doesn’t support environment variables directly, you can use them when building configurations programmatically:

#![allow(unused)]
fn main() {
McpServerConfig {
    bearer_token: std::env::var("HF_TOKEN").ok(),
    source: McpServerSource::Http {
        url: std::env::var("MCP_SERVER_URL")
            .unwrap_or_else(|_| "https://hf.co/mcp".to_string()),
        // ...
    },
    // ...
}
}

import os

McpServerConfigPy(
    bearer_token=os.getenv("HF_TOKEN"),
    source=McpServerSourcePy.Http(
        url=os.getenv("MCP_SERVER_URL", "https://hf.co/mcp")
    )
)

MCP-Related Environment Variables

Validation Rules

1. Unique Server IDs: All server id values must be unique
2. Valid URLs: HTTP URLs must start with http:// or https://
3. Valid WebSocket URLs: Must start with ws:// or wss://
4. Executable Commands: Process commands must be executable
5. Tool Name Conflicts: Use tool_prefix to avoid conflicts

Example Configurations

Single Server (Hugging Face) - Minimal

{
  "servers": [{
    "name": "Hugging Face MCP Server",
    "source": {
      "type": "Http",
      "url": "https://hf.co/mcp"
    },
    "bearer_token": "hf_xxx"
  }]
}

Single Server (Hugging Face) - Full Configuration

{
  "servers": [{
    "id": "hf",
    "name": "Hugging Face MCP",
    "source": {
      "type": "Http",
      "url": "https://hf.co/mcp",
      "timeout_secs": 30
    },
    "enabled": true,
    "tool_prefix": "hf",
    "bearer_token": "hf_xxx"
  }],
  "auto_register_tools": true,
  "tool_timeout_secs": 30,
  "max_concurrent_calls": 5
}

Multi-Server Setup

{
  "servers": [
    {
      "id": "hf",
      "name": "Hugging Face",
      "source": {"type": "Http", "url": "https://hf.co/mcp"},
      "tool_prefix": "hf",
      "bearer_token": "hf_xxx"
    },
    {
      "id": "github",
      "name": "GitHub API",
      "source": {"type": "Http", "url": "https://api.github.com/mcp"},
      "tool_prefix": "gh",
      "bearer_token": "ghp_xxx"
    },
    {
      "id": "local_fs",
      "name": "Filesystem",
      "source": {
        "type": "Process",
        "command": "mcp-server-filesystem",
        "args": ["--root", "/data", "--readonly"]
      },
      "tool_prefix": "fs"
    }
  ],
  "auto_register_tools": true,
  "tool_timeout_secs": 30,
  "max_concurrent_calls": 10
}