> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP types

> Configure MCP servers programmatically.

The Model Context Protocol (MCP) lets agents connect to external tool servers. The SDK exposes `MCPServerDetails` for declaring servers per task, and a few enums for the supported transports and auth types.

```python theme={"dark"}
from xpander_sdk import MCPServerDetails, MCPServerType, MCPServerAuthType

server = MCPServerDetails(
    type=MCPServerType.Remote,
    name="internal-docs",
    url="https://mcp.internal.acme.com",
    auth_type=MCPServerAuthType.APIKey,
    api_key="...",
)
```

You typically pass a list of these to `Agent.acreate_task(mcp_servers=[...])` to attach servers for a single run; servers configured in the Workbench are added automatically.

## `MCPServerDetails`

```python theme={"dark"}
MCPServerDetails(
    type: MCPServerType = MCPServerType.Remote,
    name: Optional[str] = None,
    command: Optional[str] = None,
    url: Optional[str] = None,
    transport: MCPServerTransport = MCPServerTransport.HTTP_Transport,
    auth_type: MCPServerAuthType = MCPServerAuthType._None,
    api_key: Optional[str] = None,
    use_secrets_manager: bool = False,
    client_id: Optional[str] = None,
    client_secret: Optional[str] = None,
    headers: Dict = {},
    env_vars: Dict = {},
    allowed_tools: List[str] = [],
    additional_scopes: List[str] = [],
    share_user_token_across_other_agents: bool = True,
)
```

| Field                                  | Type                 | Description                                                                                  |
| -------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------- |
| `type`                                 | `MCPServerType`      | `Local` (stdio) or `Remote` (HTTP/SSE).                                                      |
| `name`                                 | `str`                | Server name (used in logs and the dashboard).                                                |
| `command`                              | `str`                | For `Local` servers: the binary to run.                                                      |
| `url`                                  | `str`                | For `Remote` servers: the server endpoint.                                                   |
| `transport`                            | `MCPServerTransport` | `STDIO`, `SSE`, or `HTTP_Transport` (default).                                               |
| `auth_type`                            | `MCPServerAuthType`  | `_None`, `APIKey`, `OAuth2`, or `CustomHeaders`.                                             |
| `api_key`                              | `str`                | For `APIKey` auth.                                                                           |
| `use_secrets_manager`                  | `bool`               | Resolve the API key from the platform's secrets manager.                                     |
| `client_id` / `client_secret`          | `str`                | For `OAuth2`.                                                                                |
| `headers`                              | `dict`               | Custom headers (used with `CustomHeaders` auth or always-on).                                |
| `env_vars`                             | `dict`               | Env vars to set when launching `Local` servers.                                              |
| `allowed_tools`                        | `list[str]`          | Whitelist of tools to expose from this server. Empty = all.                                  |
| `additional_scopes`                    | `list[str]`          | Extra OAuth scopes.                                                                          |
| `share_user_token_across_other_agents` | `bool`               | When `True`, end users only authenticate once even when multiple agents use the same server. |

## Enums

### `MCPServerType`

| Value                 | Meaning                                                                |
| --------------------- | ---------------------------------------------------------------------- |
| `Local` (`"local"`)   | Run a local stdio process. Requires `command` and optional `env_vars`. |
| `Remote` (`"remote"`) | Connect to a remote HTTP / SSE server. Requires `url`.                 |

### `MCPServerTransport`

| Value                                  | Meaning                                      |
| -------------------------------------- | -------------------------------------------- |
| `STDIO` (`"stdio"`)                    | Standard input/output (Local servers).       |
| `SSE` (`"sse"`)                        | Server-sent events.                          |
| `HTTP_Transport` (`"streamable-http"`) | HTTP streaming (default for remote servers). |

### `MCPServerAuthType`

| Value                                | Meaning                                                                        |
| ------------------------------------ | ------------------------------------------------------------------------------ |
| `_None` (`"none"`)                   | No auth.                                                                       |
| `APIKey` (`"api_key"`)               | Static API key in `api_key`.                                                   |
| `OAuth2` (`"oauth2"`)                | OAuth2 with `client_id` / `client_secret`. Triggers `auth_event`s during runs. |
| `CustomHeaders` (`"custom_headers"`) | Send `headers` as auth.                                                        |

## Examples

### Local server (stdio)

```python theme={"dark"}
local_server = MCPServerDetails(
    type=MCPServerType.Local,
    name="my-local-mcp",
    command="python -m my_mcp_module",
    transport=MCPServerTransport.STDIO,
    env_vars={"DEBUG": "1"},
)
```

### Remote with API key

```python theme={"dark"}
remote_server = MCPServerDetails(
    type=MCPServerType.Remote,
    name="docs-mcp",
    url="https://mcp.docs.acme.com",
    transport=MCPServerTransport.HTTP_Transport,
    auth_type=MCPServerAuthType.APIKey,
    api_key="sk-...",
)
```

### Remote with OAuth2

```python theme={"dark"}
oauth_server = MCPServerDetails(
    type=MCPServerType.Remote,
    name="github-mcp",
    url="https://mcp.github.com",
    auth_type=MCPServerAuthType.OAuth2,
    client_id="...",
    client_secret="...",
    additional_scopes=["repo", "read:user"],
)
```

OAuth2 servers fire `auth_event`s during a run when end-user authorization is required. Register an [`@on_auth_event`](/developers/sdk-reference/decorators/on-auth-event) handler to route the OAuth URL to your UI.

### Per-task server attachment

```python theme={"dark"}
task = await agent.acreate_task(
    prompt="Search our internal docs for the Q4 roadmap.",
    mcp_servers=[remote_server],
)
```

These are appended to the agent's persistent MCP config for this task only.

### Limit which tools are exposed

```python theme={"dark"}
restricted = MCPServerDetails(
    type=MCPServerType.Remote,
    name="github-mcp",
    url="https://mcp.github.com",
    auth_type=MCPServerAuthType.OAuth2,
    client_id="...",
    client_secret="...",
    allowed_tools=["search_repositories", "get_issue"],
)
```

Only `search_repositories` and `get_issue` will be exposed to the agent: every other tool the server offers is hidden.

## OAuth response types (for `@on_auth_event` payloads)

When OAuth flows fire, `event.data` is shaped like one of these:

| Type                       | Field                        | Description                |
| -------------------------- | ---------------------------- | -------------------------- |
| `MCPOAuthGetTokenResponse` | `type: MCPOAuthResponseType` | Discriminator.             |
|                            | `data: ...`                  | One of the variants below. |

| Variant                                 | Fields                             |
| --------------------------------------- | ---------------------------------- |
| `MCPOAuthGetTokenLoginRequiredResponse` | `url`, `server_url`, `server_name` |
| `MCPOAuthGetTokenTokenReadyResponse`    | `access_token`                     |
| `MCPOAuthGetTokenGenericResponse`       | `message`                          |

`MCPOAuthResponseType` values: `not_supported`, `login_required`, `token_issue`, `token_ready`.

Use these in your auth handler to display the right state to the end user (login URL vs. "we're working on it" vs. success).