lane-mcp-auth

OAuth 2.1 resource server and consent gate for an MCP server behind Lane — the Python distribution of @getonlane/mcp-auth.

Docs — overview · quickstart · the gate · reference

pip install lane-mcp-auth          # core
pip install 'lane-mcp-auth[fastmcp]'   # + the FastMCP helpers

Your server verifies bearer tokens, publishes the discovery document clients need, and refuses every tool until the caller holds a recorded, revocable grant.

Set up with one command where the server runs. It pairs with the Lane console and writes the credential to .env; the secret never passes through a browser:

python -m lane_mcp_auth setup https://acme.example/mcp --name="Acme shop"

Pass client_id and announce_secret and the server announces the resource it serves on its first guarded call, so Lane binds the hostname to the credential.

from lane_mcp_auth import LaneMcpAuth

auth = LaneMcpAuth(
    resource="https://acme.example/mcp",
    connections=connections,   # yours: this is server-side state
    exchanger=exchanger,
)

The three tiers

Registration is the floor. Omitting a scope means any connected caller, never anyone: a session that has not registered has nothing anyone can revoke, so a tool answering it would be answering something nobody can withdraw.

With FastMCP

from lane_mcp_auth.fastmcp import register_step_up_tool, guarded

register_step_up_tool(mcp, auth)

@mcp.tool()
@guarded(auth, "read_orders", scope="email")
async def read_orders(ctx) -> str:
    return await orders_for(ctx)

Purchases

A tool marked with @price never buys when an agent calls it. It answers with a proposal and a ticket; the agent builds a plan with the five lane_plan_* tools this package registers, and the user approves it in their Lane wallet. Lane then calls the tool once per approved step with an execution grant.

from lane_mcp_auth import HttpProposalRecorder, PlanForwarder, Quote
from lane_mcp_auth.fastmcp import enable_lane_auth, lane, price

enable_lane_auth(
    mcp,
    auth,
    purchase={"host": "courts.example", "recorder": HttpProposalRecorder(base_url=LANE, org_key=ORG_KEY)},
    plans=PlanForwarder(exchanger=exchanger, lane_mcp_url="https://mcp.getonlane.com/mcp"),
)

@mcp.tool()
@price(cents=2500)
async def book_court(ctx, court: str) -> str:
    return await book(court)          # runs only under an execution grant

async def quote_flight(args, claims) -> Quote:
    q = await price_for(args["offer_id"])
    return Quote(amount_cents=q.cents, description=q.summary, expires_at=q.valid_until)

@mcp.tool()
@price(quote=quote_flight)
async def book_flight(ctx, offer_id: str) -> str:
    return await book(offer_id, lane().approved_amount_cents)   # runs only under an execution grant

The docs page charging for a purchase covers reservations, what runs when, and the 7-day plan limit.

Tools that cost less than a cent

Lane bills a tool marked with @subcent on every call, in USD microdollars, from 1 to 9,999. The user approves no single call. Lane reserves the amount before your handler runs, commits it after a good result, and releases it after a failed one.

from lane_mcp_auth import HttpBillingClient, SubcentBilling
from lane_mcp_auth.fastmcp import enable_lane_auth, subcent

billing = SubcentBilling(
    client=HttpBillingClient(base_url=LANE, org_key=ORG_KEY),
    resource="https://tools.example/mcp",
)

enable_lane_auth(mcp, auth, subcent=billing)

@mcp.tool()
@subcent(micros=2500)  # $0.0025 a call
async def search_products(ctx, q: str) -> str:
    """Search the merchant catalog."""
    return await search(q)

The price reaches tools/list as lane/price. Lane hashes what the tool publishes -- the name, the description, the schemas, the Lane tags and the price -- and that hash names the revision Lane bills. Lane bills a call only while it holds that exact revision as active. Lane refuses a changed tool with tool_revision_not_active until it activates the new revision. Every other tool on the server still runs.

Never authorize on the token's scopes

claims.scopes is the token's own claim: empty before the step-up, stale after. Authority lives in the connection and is reachable only through has_scope() / effective_scopes(), because Lane decides it at exchange time and can refuse an exchange it would previously have allowed. A signed claim cannot be withdrawn.

Parity with the TypeScript

Same invariants, same names where Python idiom allows. The TypeScript package is the reference implementation; where the two could drift — scope filtering, the metadata paths, the gate's decision table — see SCOPE.md for what is implemented here and what is not yet.

Licence

MIT