MCP

The alter_sdk.mcp module integrates with FastMCP so any MCP server can ship as a full OAuth 2.0 Authorization Server backed by Alter’s hosted IDP flow.

Requires the mcp extra:

pip install 'alter-sdk[mcp]'

Note

When upgrading an existing environment from fastmcp 3.2.x or earlier to 3.3+, use pip install --upgrade --force-reinstall fastmcp (or recreate the virtual environment). FastMCP 3.3 split its distribution into a fastmcp meta-package plus a fastmcp-slim implementation package, and an in-place upgrade can leave a broken install that fails with ModuleNotFoundError: No module named 'fastmcp.server'.

from fastmcp import FastMCP
from alter_sdk import App
from alter_sdk.mcp import AlterMCP, AlterAuthProvider, AlterContext

mcp = FastMCP("my-server")
alter_app = App(api_key="alter_rk_…")
alter = AlterMCP(alter_app)

@mcp.tool()
@alter.tool(provider="provider-id")
async def list_resources(ctx: AlterContext, query: str) -> list[dict]:
    resp = await ctx.request(
        "GET",
        "https://api.provider.example/v1/resources",
        query_params={"q": query},
    )
    return resp.json()

if __name__ == "__main__":
    mcp.run()

AlterMCP

AlterMCP(vault: App | Agent)

Wrapper around an SDK client that exposes the @alter.tool() decorator.

tool

def tool(
    provider: str,
    *,
    label: str | None = None,
    agent: Agent | None = None,
) -> Callable[[F], F]

Parameter	Type	Default	Description
provider	str	—	OAuth provider id (e.g. "provider-id").
label	str | None	None	Optional sibling-grant label for multi-grant resolution.
agent	Agent | None	None	Optional Agent whose identity should drive this tool’s requests. Same-Task nesting records the outer agent as parent_agent.

The decorator:

1. Creates an AlterContext pre-configured with the provider and optional label.
2. Sets an ambient audit ContextVar so vault.request() calls inside the tool body pick up the tool name automatically.
3. Hides the AlterContext parameter from FastMCP’s generated tool schema.
4. Catches GrantNotFoundError and returns an MCP error with a fresh Connect URL.
5. Catches ScopeReauthRequiredError and returns an MCP error with a re-auth hint.

Use app.with_constraints(...) / agent.with_constraints(...) before passing the SDK client to AlterMCP when a tool needs enforceable scope narrowing or a request rule.

from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
@alter.tool(provider="provider-id")
async def list_resources(ctx: AlterContext) -> list[dict]:
    resp = await ctx.request(
        "GET",
        "https://api.provider.example/v1/resources",
    )
    return resp.json()

AlterContext

Per-tool-call request context injected by @alter.tool(). Not constructed directly.

AlterContext(
    vault: App | Agent,
    *,
    provider: str,
    label: str | None = None,
    context: dict[str, str] | None = None,
)

Properties

Property	Type	Description
provider	str	The OAuth provider id declared on the decorator.
label	str | None	Optional sibling-grant label declared on the decorator.

request

Forwards to the underlying vault.request() with provider= and context= pre-filled. Tool implementations only specify method + URL.

resp = await ctx.request(
    "GET",
    "https://api.provider.example/v1/resources",
    query_params={"q": "example"},
)

proxy_request

Forwards to the underlying vault.proxy_request() with provider=, label=, and context= pre-filled. Use this for restricted grants or HITL / approval-gated calls.

result = await ctx.proxy_request(
    "POST",
    "https://api.example.com/v1/actions",
    json={"approved": True},
)

AlterAuthProvider

A FastMCP OAuthProvider that turns any MCP server into a full OAuth 2.0 Authorization Server backed by Alter’s IDP flow. Spec-compliant MCP clients can discover, register, authorize, and obtain tokens without mcp-remote or any other shim.

AlterAuthProvider(
    vault: App | Agent,
    *,
    base_url: str,
    providers: dict[str, list[str]] | None = None,
)

Parameter	Type	Default	Description
vault	App | Agent	—	SDK client to back the OAuth flow.
base_url	str	—	Public URL where the MCP server is mounted (e.g. "https://mcp.example.com"). Required for OAuth metadata discovery.
providers	dict[str, list[str]] | None	None	Map of provider_id → required scopes for the Connect flow.

from fastmcp import FastMCP
from alter_sdk import App
from alter_sdk.mcp import AlterAuthProvider

vault = App(api_key="alter_rk_…")
auth = AlterAuthProvider(
    vault,
    base_url="https://mcp.example.com",
    providers={"provider-id": ["resources:read"]},
)

mcp = FastMCP("Resources", auth=auth)

Pair with AlterFastAPI.auth_provider() when the same vault should serve both FastAPI and MCP traffic.

AccessToken

Re-exported by alter_sdk.mcp so subclass authors can annotate load_access_token / verify_token overrides on AlterAuthProvider subclasses without reaching into FastMCP’s namespace directly.

from alter_sdk.mcp import AccessToken