feat(keycardai-mcp): interrupt-compatible auth mode for the langchain adapter (ECO-332)

[devin-ai-integration]

Summary

An agent that mixes keycardai-langchain's KeycardGrantMiddleware (brokered REST tools, pauses with an authorization_required interrupt) with the MCP client's langchain adapter (hands the model a request_authentication tool) had to render two auth UXs. This unifies them.

Interrupt mode, opt-in. LangChainClient(mcp_client, interrupt_on_auth=True) makes a wrapped tool pause the run with the same payload the middleware's _interrupt_payload produces, with MCP servers standing in for resource URLs:

async def invoke_tool(**kwargs):
    if self._interrupt_on_auth:
        await self._interrupt_if_authorization_required()  # -> langgraph interrupt(payload)
    ...

# payload, keys identical to KeycardGrantMiddleware's:
{"type": "authorization_required", "resources": ["linear"],
 "authorization_url": challenges[0]["authorization_url"],
 "errors": {"linear": {...}}, "message": "Access to the resources above ..."}

The challenge is read from sessions where session.requires_user_action is true. While the mode is on, get_auth_tools() returns []; with the mode off (the default) nothing about the auth-tools path changes. langgraph is imported lazily inside _interrupt, so the adapter still depends on langchain-core alone.

Dynamic tool binding. create_agent fixes its tool list at import, before any user has connected, which is what pushed the demo into a hand-written wrapper that hid the server's state/query/team/project parameters. Two supported shapes now, both documented: build the agent's tools after connect() (get_tools(), per request), or get_lazy_tools() — list_mcp_tools / call_mcp_tool, which connect on first call and then report and invoke the server's real schemas. tool_allowlist=[...] restricts what is exposed either way, so a 67-tool server does not flood the context window.

Note on what is not possible: LangGraph's ToolNode resolves tool calls against the tools bound at create_agent time, so tools discovered later cannot be registered retroactively — hence the list_mcp_tools + call_mcp_tool pair rather than per-tool lazy stubs.

Docs (both READMEs): middleware grants vs. MCP client, tool_resources={"call_mcp_tool": []} so the middleware exchanges nothing for MCP-backed tools, the shared /auth/mcp/callback route calling coordinator.handle_completion(dict(request.query_params)), and the interrupt opt-in.

Tests run the tool inside a real checkpointed LangGraph run (an interrupt only exists inside a run) and compare the payload against KeycardGrantMiddleware._interrupt_payload itself, not a copy of its literal.

packages/mcp 553 passed (65% coverage, gate 60%), packages/langchain 46 passed, ruff check clean. No code in the langchain middleware package was touched — only its README.

Link to Devin session: https://app.devin.ai/sessions/cbdad0905a154ec4855c7c644a247eed
Open in Devin Desktop: https://app.devin.ai/desktop/session/cbdad0905a154ec4855c7c644a247eed?variant=devin
Requested by: @Larry-Osakwe

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring