Build your first agent in just a few minutes with [Rasa Copilot](https://hello.rasa.com/?utm_source=docs&utm_medium=referral&utm_campaign=docs_cta).

# New Beta Feature in 3.14

Rasa 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.

MCP servers allow your Rasa agent to connect to external services and APIs through the [Model Context Protocol](https://modelcontextprotocol.io/). These servers expose tools that your agent can use [directly in flows](/content/docs/reference/primitives/flow-steps/#calling-an-mcp-tool/index.html) or provide to [autonomous sub agents](/content/docs/reference/config/agents/overview-agents/#how-to-use-sub-agents/index.html) for dynamic decision-making.

## Basic Configuration

MCP servers are configured in your `endpoints.yml` file.

```yaml
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:

```yaml
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.

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

```yaml
mcp_servers:
  - name: custom_header_server
    url: https://api.example.com
    type: https
    api_key: "${API_KEY}"
    header_name: "X-API-Key"
    header_format: "{key}"
```

```yaml
mcp_servers:
  - name: oauth_server
    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:data write:data"
```

```yaml
mcp_servers:
  - name: token_server
    url: https://api.example.com
    type: https
    token: "${ACCESS_TOKEN}"
```

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:

```yaml
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:

```yaml
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:

```yaml
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}"
```

## Call-time credential hooks (`pre_call_hook`)

Call-time credential hooks resolve **per-conversation secrets** only when an outbound MCP tool call is about to be made. Rasa invokes your hook, merges the returned metadata into MCP `_meta`, and never writes secret values to slots, the tracker, Kafka, or the Inspector.

Use `pre_call_hook` when credentials are:

- **Per user or per conversation** (keyed by `sender_id`)
- **Stored encrypted** in your own vault or secret manager
- **Required on every tool call** to a specific MCP server

The hook applies to:

- **Direct MCP tool calls in Flows** — `call` steps that reference `mcp_server` in a flow (see [Calling an MCP Tool](/content/docs/reference/primitives/flow-steps/#calling-an-mcp-tool/index.html))
- **ReAct external MCP tools** — tools from MCP servers listed in the sub agent's `connections` section

Flows and sub agents reference MCP servers by **name only**. There is no `pre_call_hook` on individual flow steps or per sub-agent connection entries — configure the hook in each MCP server entry in `endpoints.yml`.

```yaml
mcp_servers:
  - name: appointment_booking
    url: http://appointment-booking:8000/mcp/
    type: http
    pre_call_hook: custom.call_time_credentials.resolve_appointment_booking_meta
    meta_map:
      static:
        api_version: "v2"
```

When both `meta_map` and `pre_call_hook` are set, static `meta_map` is merged first; hook `metadata` wins on key collision.

### Hook contract

Add `pre_call_hook` as a dotted import path to a module-level sync or async function. Use `async def` when the hook performs I/O (for example fetching from a secret store). Import types from `rasa.shared.agents.outbound_call_hook`:

```python
from rasa.shared.agents.outbound_call_hook import (
    MCPOutboundCallContext,
    OutboundCallResult,
)
```

Rasa calls the hook as `hook(context)` and passes a frozen, read-only `MCPOutboundCallContext`:

| Field | Description |
| --- | --- |
| `sender_id` | Conversation id — use as your secret-store lookup key |
| `tool_name` | Tool being called (flow `call` step, MCP tool name, or custom tool name) |
| `server_name` | MCP server name for flow / ReAct MCP calls; `None` for custom tools |
| `flow_id`, `step_id` | Set for direct MCP tool calls in flows; otherwise `None` |
| `agent_id` | Sub-agent id for ReAct MCP calls; otherwise `None` |

The hook must return an `OutboundCallResult` with a `metadata` dict. `OutboundCallResult` has a single `metadata` field; Rasa merges it onto the wire. For convenience, a plain `dict` is accepted and normalized to `OutboundCallResult(metadata=...)`. Never put secrets in flow `mapping.input` or tool argument mappings.

## Passing metadata to tools (`meta_map`)

Remote MCP tool calls can include a protocol-level `_meta` object (when supported by your MCP client SDK) so the server receives context that does not appear in the tool arguments the LLM fills. In Rasa, this is configured per server with optional `meta_map` in `endpoints.yml`:

- **`static`**: Fixed string key-value pairs always merged into `_meta` (for example API version or environment labels). Use for **non-secret** context.
- **`from_slots`**: A list of `{ slot, param }` entries. For each entry, the current value of the named slot (from the tracker / agent input) is sent as `_meta[param]`. Prefer [`pre_call_hook`](/content/docs/reference/integrations/mcp-servers/#call-time-credential-hooks-pre_call_hook/index.html) instead of slots when the value is a secret.

When both `meta_map` and `pre_call_hook` are set, static `meta_map` is merged first; hook `metadata` wins on key collision.

```yaml
mcp_servers:
  - name: internal_api
    url: http://internal-api:8000/mcp/
    meta_map:
      from_slots:
        - slot: user_id
          param: user_id
        - slot: role
          param: user_role
      static:
        api_version: "v2"
        source: "rasa_agent"
```

If `meta_map` is omitted or has no `from_slots` entries, Rasa still sends any `static` entries. Slot values are read from the same agent input used for the ReAct turn; ensure the slot is set before the tool runs if you map it in `from_slots`.

Older MCP Python SDK releases that do not support a `meta` parameter on `call_tool` are still supported: Rasa detects this and falls back to calling without metadata so tools keep working; once the SDK supports `meta`, metadata is sent automatically.

## 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 `meta_map.from_slots` is set, every referenced `slot` exists in the domain (training / `rasa train` validation)
- If `pre_call_hook` is set, the import path resolves to a callable (training / `rasa train` validation)

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