Skip to main content
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="...",
)
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

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,
)
FieldTypeDescription
typeMCPServerTypeLocal (stdio) or Remote (HTTP/SSE).
namestrServer name (used in logs and the dashboard).
commandstrFor Local servers: the binary to run.
urlstrFor Remote servers: the server endpoint.
transportMCPServerTransportSTDIO, SSE, or HTTP_Transport (default).
auth_typeMCPServerAuthType_None, APIKey, OAuth2, or CustomHeaders.
api_keystrFor APIKey auth.
use_secrets_managerboolResolve the API key from the platform’s secrets manager.
client_id / client_secretstrFor OAuth2.
headersdictCustom headers (used with CustomHeaders auth or always-on).
env_varsdictEnv vars to set when launching Local servers.
allowed_toolslist[str]Whitelist of tools to expose from this server. Empty = all.
additional_scopeslist[str]Extra OAuth scopes.
share_user_token_across_other_agentsboolWhen True, end users only authenticate once even when multiple agents use the same server.

​
Enums

​
MCPServerType

ValueMeaning
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

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

​
MCPServerAuthType

ValueMeaning
_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"],
)
OAuth2 servers fire 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],
)
These are appended to the agent’s persistent MCP config for this task only.

​
Limit which tools are exposed

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:
TypeFieldDescription
MCPOAuthGetTokenResponsetype: MCPOAuthResponseTypeDiscriminator.
data: ...One of the variants below.
VariantFields
MCPOAuthGetTokenLoginRequiredResponseurl, server_url, server_name
MCPOAuthGetTokenTokenReadyResponseaccess_token
MCPOAuthGetTokenGenericResponsemessage
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).