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.
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.
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="...",
)
Agent.acreate_task(mcp_servers=[...]) to attach servers for a single run; servers configured in the Workbench are added automatically.
MCPServerDetails
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_events during runs. |
CustomHeaders ("custom_headers") | Send headers as auth. |
Examples
Local server (stdio)
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
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
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"],
)
auth_events during a run when end-user authorization is required. Register an @on_auth_event handler to route the OAuth URL to your UI.
Per-task server attachment
task = await agent.acreate_task(
prompt="Search our internal docs for the Q4 roadmap.",
mcp_servers=[remote_server],
)
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"],
)
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).
