Skip to main content

MCP Servers

MCP servers allow your Rasa agent to connect to external services and APIs through the Model Context Protocol. These servers expose tools that your agent can use directly in flows or provide to autonomous sub agents for dynamic decision-making.

Basic Configuration​

MCP servers are configured in your endpoints.yml file.

mcp_servers:
  - name: trade_server
    url: http://localhost:8080
    type: http

The following fields are required:

  • name: A unique identifier for the MCP server
  • url: The URL where the MCP server is running
  • type: The server type (currently supports http and https)

Multiple MCP Servers​

You can configure multiple MCP servers to connect to different services:

mcp_servers:
  - name: inventory_server
    url: http://localhost:8080
    type: http
  - name: payment_server
    url: https://api.payment-service.com
    type: https
  - name: customer_database
    url: http://localhost:9000
    type: http

Each server can expose different tools and be used independently in your flows or by different sub agents. Server names must be unique across all MCP servers. If you attempt to configure multiple servers with the same name, Rasa will raise a validation error during startup.

Authentication​

MCP servers support multiple authentication methods for connecting to external services:

  • API Key: Static key attached as Authorization: Bearer <token>
  • OAuth 2.0 (Client Credentials): Automatic token retrieval with client ID/secret
  • Pre-issued Token: Direct token usage until expiry

Authentication settings are specified using additional parameters in your MCP server configuration.

mcp_servers:
  - name: secure_api_server
    url: https://api.example.com
    type: https
    api_key: "${API_KEY}"

The $ syntax is required for the following sensitive parameters:

  • api_key
  • token
  • client_secret

This ensures that they are not stored in plain text in your configuration files. For other parameters like client_id, using the $ syntax is optional — you can either reference an environment variable using the $ syntax or provide the value directly in the configuration.

Advanced Configuration​

Custom Headers​

You can specify custom headers for API key authentication:

mcp_servers:
  - name: custom_auth_server
    url: https://api.example.com
    type: https
    api_key: "${API_KEY}"
    header_name: "X-Custom-Auth"
    header_format: "Bearer {key}"

OAuth 2.0 Scopes​

For OAuth 2.0 authentication, you can optionally pass in scope, audience, and timeout:

mcp_servers:
  - name: oauth_server_with_scopes
    url: https://api.example.com
    type: https
    oauth:
      client_id: "${CLIENT_ID}"
      client_secret: "${CLIENT_SECRET}"
      token_url: "https://auth.example.com/oauth/token"
      scope: "read:users write:orders admin:settings" # Optional: scopes for the OAuth 2.0 token
      audience: "https://api.example.com" # Optional: audience for the OAuth 2.0 token
      timeout: 10 # Optional: timeout for the OAuth 2.0 token

Complete Example​

Here's a comprehensive example showing multiple MCP servers with different authentication methods:

mcp_servers:
  # Public API with API key
  - name: weather_service
    url: https://api.weather.com
    type: https
    api_key: "${WEATHER_API_KEY}"
  
  # Internal service with OAuth
  - name: internal_database
    url: https://db.internal.com
    type: https
    oauth:
      client_id: "${DB_CLIENT_ID}"
      client_secret: "${DB_CLIENT_SECRET}"
      token_url: "https://auth.internal.com/oauth/token"
      scope: "database:read database:write"
  
  # Local development server
  - name: local_tools
    url: http://localhost:8080
    type: http
  
  # Service with custom header authentication
  - name: custom_auth_server
    url: https://api.example.com
    type: https
    api_key: "${API_KEY}"
    header_name: "X-API-Key"
    header_format: "{key}"

Validation​

Rasa validates MCP server configurations to ensure:

  • Server type is either http or https
  • Name and URL are not empty
  • Sensitive parameters (API keys, tokens, secrets) are properly referenced using environment variables
  • OAuth configuration includes all required fields

If validation fails, Rasa will provide specific error messages to help you fix the configuration.

Last updated on