---
title: "MCP Integration"
description: "Connecting MCP servers to Orchid agents: none, passthrough, and OAuth auth modes."
package: orchid
section: concepts
html_url: https://orchestratorindex.com/concepts/mcp
markdown_url: https://orchestratorindex.com/concepts/mcp.md
---

# MCP Integration

Orchid agents can call any MCP server over Streamable HTTP or SSE transport. The connection is configured per-server in `agents.yaml`; the framework handles capability discovery, caching, and per-user authentication transparently.

## The MCP client interface

`OrchidMCPClient` in `orchid_ai/core/mcp.py` combines two narrower ABCs:

- **`OrchidMCPToolCaller`** — code that only invokes tools depends on this
- **`OrchidMCPDiscoverable`** — code that discovers capabilities depends on this

`StreamableHttpMCPClient` in `orchid_ai/mcp/client.py` is the concrete implementation. It keeps an in-memory capability cache that is populated once (proactively at startup or session-start) and flushed only via explicit `invalidate_cache()` calls.

## Three auth modes

Each MCP server declaration carries a `mode` under `auth:`; for MCP-2025-03-26-compliant servers that is the only field — no credentials, no endpoints, no client IDs live in config. Non-compliant servers can opt into explicit endpoints and credentials with `auth.manual_registration` (see [OAuth & Authentication](/concepts/oauth)).

```yaml title="agents.yaml"
mcp_servers:
  - name: public-weather
    url: https://weather.example.com/mcp
    # auth defaults to: mode: none

  - name: tenant-catalog
    url: https://catalog.example.com/mcp
    auth:
      mode: passthrough

  - name: external-crm
    url: https://crm.example.com/mcp
    auth:
      mode: oauth
```

```markdown title="orchid.md"
---
mcp_servers:
  - name: public-weather
    url: https://weather.example.com/mcp
    # auth defaults to: mode: none

  - name: tenant-catalog
    url: https://catalog.example.com/mcp
    auth:
      mode: passthrough

  - name: external-crm
    url: https://crm.example.com/mcp
    auth:
      mode: oauth
---
```

| Mode | Behaviour |
|------|-----------|
| `none` (default) | No auth headers. For local or public servers. |
| `passthrough` | Forwards the graph's `OrchidAuthContext` bearer token on every call. The MCP server and Orchid share the same identity provider. |
| `oauth` | Full MCP 2025-03-26 flow. When no stored token exists, the client raises `OrchidMCPAuthRequiredError`; the authorization route then discovers protected resource metadata, authorization server metadata, and dynamic client registration, and stores per-user tokens in `OrchidMCPTokenStore`. Non-compliant servers can seed endpoints via `auth.manual_registration` instead. See [OAuth & Authentication](/concepts/oauth). |

> `OrchidMCPServerConfig` is declared with `extra="forbid"`. Adding `cache_ttl:` to a server block raises a Pydantic validation error at startup. Capability caches have no TTL; they live for the process lifetime and are flushed via `invalidate_cache()` or `OrchidSessionWarmer.invalidate_user()`.
> 
> *info note.*

## Proactive capability warming

The framework warms MCP capability caches at well-defined boundaries so the per-request hot path never pays discovery cost:

| Boundary | What gets warmed |
|----------|-----------------|
| Process startup | Every `auth.mode: none` server |
| User session start (`POST /session/warm`) | Every `passthrough` and `oauth` server |
| Post-OAuth callback | The freshly-authorised server |

`OrchidSessionWarmer` drives all three boundaries. It is idempotent per `(tenant_key, user_id)` pair.

## External reading

- [Model Context Protocol specification](https://modelcontextprotocol.io)
- [MCP 2025-03-26 authorization spec](PLACEHOLDER)
- [RFC 9728: OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)
- [RFC 8414: OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414)
- [RFC 7591: OAuth 2.0 Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591)
