Integrating an MCP Server - Rasa Documentation

New Beta Feature in 3.14Rasa supports native integration of MCP servers.This feature is in a beta (experimental) stage and may change in future Rasa versions. We welcome your feedback on this feature.

Overview

Rasa integrates with Model Context Protocol (MCP) servers to connect your agent to external APIs, databases, and other services. MCP servers expose tools that your agent can use directly in flows or provide to ReAct style sub agents for dynamic decision-making.

Defining an MCP Server

Define your MCP servers in the endpoints.yml file:

endpoints.yml

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

For detailed information on available authentication methods and other parameters, head over to the reference page. To send server-side context on every tool call without exposing it to the LLM, configure optional meta_map on the MCP server in endpoints.yml.

Using an MCP tool in a flow

Use MCP tools directly in flows with the call step, specifying input/output mappings:

flows.yml

flows:
  buy_order:
    description: helps users place a buy order for a particular stock
    steps:
    - collect: stock_name
    - collect: order_quantity
    - action: check_feasibility
      next:
        - if: slots.order_feasible is True
          then:
            - call: place_buy_order  # MCP tool name
              mcp_server: trade_server  # MCP server where tool is available
              mapping:
                input:
                - param: ticker_symbol  # tool parameter name
                  slot: stock_name      # slot to send as value
                - param: quantity
                  slot: order_quantity
                output:
                - slot: order_status     # slot to store results
                  value: result.structuredContent.order_status.success
        - else:
            - action: utter_invalid_order
              next: END

This way of directly invoking tools from flows avoids having to write any custom action code just for the purpose of integrating with external APIs.

Tool Results and Output Handling

MCP tools return results in two possible formats:

Structured Content

When tools provide an output schema (see for example), you get structured data as output:

{
  "result": {
    "structuredContent": {
      "order_status": {"success": true, "order_id": "bcde786f1"}
    }
  }
}

In such a case, specific values from the resulting dictionary can be accessed using the dot notation:

  - call: place_buy_order
    mcp_server: trade_server
    ...
    output:
    - slot: order_status
      value: result.structuredContent.order_status.success

Unstructured Content

When the invoked tool has no output schema is defined, the entire output is captured as a serialized string:

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"order_status\": {\"success\": true, \"order_id\": \"bcde786f1\"}"
      }
    ],
  }
}

You can still use the dot notation to capture the output but the complete serialized string will have to be captured in the slot.

output:
- slot: order_data
  value: result.content

Dynamic selection of tools in an autonomous step

Flows can also contain autonomous steps, where the business logic is dynamically figured out at runtime, based on the available context and tools from the MCP server. In order to do so, Rasa requires creation of ReAct sub agents.

Sub agent Configuration

Each sub agent which has access to MCP tools operates in a ReAct loop, determining which tools to call based on the conversation context. To create a sub agent, add a folder specific to that agent in the sub_agents/ directory of your rasa agent:

your_project/
├── config.yml
├── domain/
├── data/flows/
└── sub_agents/
    └── stock_explorer/
        ├── config.yml
        └── prompt_template.jinja2  # optional

Configure the agent in sub_agents/stock_explorer/config.yml:

sub_agents/stock_explorer/config.yml

# Basic agent information
agent:
  name: stock_explorer
  description: "Agent that helps users research and analyze stock options"

# MCP server connections
connections:
  mcp_servers:
  - name: trade_server
    include_tools:   # optional - specify which tools to include
    - find_symbol
    - get_company_news
    - apply_technical_analysis
    - fetch_live_price
    exclude_tools:   # optional - tools to exclude
    - place_buy_order
    - view_positions

Add a configuration block when you need LLM settings, intermediate messages (enabled by default for ReAct; implemented as tool acknowledgements), or other options. More details on available configuration parameters can be found in the reference section.

Invoking a sub agent

A sub agent can be invoked from a flow using the call step:

flows.yml

flows:
  stock_investment_research:
    description: helps research and analyze stock investment options
    steps:
    - call: stock_explorer  # runs until agent signals completion

A sub agent remains active until it signals a completion by itself or it meets a defined criteria, for e.g. -

flows.yml

flows:
  stock_investment_research:
    description: helps research and analyze stock investment options
    steps:
    - call: stock_explorer
      exit_if:
        - slots.user_satisfied is True

Here, stock_explorer agent will keep running until the user_satisfied slot is not set to True. To read more details about the runtime execution of a ReAct style sub agent inside Rasa, head over to the reference documentation.

Selective Tool Access

You can have fine-grained control over the specific MCP tools a sub agent can access by using the include_tools and exclude_tools properties in the agent configuration:

sub_agents/restricted_agent/config.yml

connections:
  mcp_servers:
  - name: trade_server
    include_tools:     # only allow specific tools
    - find_symbol
    - get_company_news
    exclude_tools:     # explicitly block dangerous operations
    - place_buy_order
    - delete_account
  - name: analytics_server
    exclude_tools:     # block admin-only tools
    - admin_analytics

Customization

A React style sub agent’s behaviour can be customized by one of the three modes:

Custom prompt templates - Include specific instructions and slot context
Python customization modules - Override agent behavior with custom python classes
Additional tools - Add Python-based tools alongside existing tools from MCP servers

See the Sub Agents Reference for detailed customization options.

Error handling

When an MCP tool call or sub agent call fails at runtime, Rasa cancels the active flow and triggers pattern_internal_error. The pattern frame exposes structured context in context.info so you can customize the user-facing response—for example by tool name, agent name, or failure type. See the context.info field reference for available keys. Override pattern_internal_error in your flows.yml and branch on context.info.error_source, or on a specific context.info.tool_name or context.info.agent_name. See Handling agent and MCP tool failures for a complete example.

Best Practices

MCP Server Setup

Define servers in endpoints.yml for consistency with other Rasa endpoints.
Use descriptive server names that indicate their purpose.
Ensure MCP servers are accessible from your Rasa environment.

Tool Usage in Flows

Always account for both structured and unstructured response content from tools.
Use clear parameter and slot names for maintainability.

Security Considerations

Use include_tools to provide only necessary tools for security.
Use exclude_tools to block sensitive or dangerous operations.
Set clear exit conditions to prevent infinite loops.
Limit context sharing to necessary slots only.
Prefer pre_call_hook on MCP servers (and build_custom_tool_call_metadata for ReAct custom tools) for per-conversation secrets: credentials are resolved only at outbound call time and are not stored in slots or the tracker.
Use meta_map for static, non-secret server context (API version labels, non-sensitive identifiers from slots). Those values are not part of tool schemas shown to the LLM, and Rasa avoids logging or telemetry leakage of metadata values (key names only where needed).
Regularly audit agent permissions and access to tools.

​Overview

​Defining an MCP Server

​Using an MCP tool in a flow

​Tool Results and Output Handling

​Structured Content

​Unstructured Content

​Dynamic selection of tools in an autonomous step

​Sub agent Configuration

​Invoking a sub agent

​Selective Tool Access

​Customization

​Error handling

​Best Practices

​MCP Server Setup

​Tool Usage in Flows

​Security Considerations

Overview

Defining an MCP Server

Using an MCP tool in a flow

Tool Results and Output Handling

Structured Content

Unstructured Content

Dynamic selection of tools in an autonomous step

Sub agent Configuration

Invoking a sub agent

Selective Tool Access

Customization

Error handling

Best Practices

MCP Server Setup

Tool Usage in Flows

Security Considerations