A session only sees tools it selects. The proxy’s
toolServer and a per-session mcpServers entry select themselves; workspace integrations need tools.
Your tools with the proxy (Node)
The session proxy attaches your MCP endpoint to every chat, mints a short-lived token for the signed-in user, and refreshes it on every message, approval, and answer.1
Add toolServer to the proxy
OPENGENI_TOOL_SERVER_URL instead of url. Tools not in approvals.ask run without asking; ask: true gates every tool. Tools act as the user who started the chat.2
Serve your tools, scoped to the verified user
With the official MCP SDK (Mount it next to the proxy: in Next.js,
bun add @modelcontextprotocol/sdk zod):export const POST = mcp; export const GET = mcp; in app/api/mcp/route.ts (keep mcp itself unexported there: next build rejects route exports other than HTTP methods); in Express, app.all("/api/mcp", toNodeMiddleware(mcp)) from @opengeni/sdk/express; in Hono, app.all("/api/mcp", toHonoHandler(mcp)) from @opengeni/sdk/hono.Scope every query to the verified user. A record id from the model is only a lookup key: rename_post must refuse a post the user does not own.examples/tool-server.
Verify the token from Python, Rails, Go...
Verify the token from Python, Rails, Go...
It is an HS256 JWT in
Authorization: Bearer with iss "opengeni-session-proxy", aud your tool server URL, sub the user id, and optional tenant. Print the signing key once with await deriveToolTokenKey() from @opengeni/sdk/tool-auth and store it as OPENGENI_TOOL_TOKEN_KEY in the other service.Per-session MCP server with a per-user token (any backend)
With a Django or Rails proxy, attach the server and rotate its token yourself.1
Attach and select the server when creating the session
2
Rotate the token on every message
beforeForwardMessage runs on your server before each message. Return a fresh token and any per-message context:3
Authorize every call in your MCP server
Validate the token and derive the tenant and user from it. Check that every record id the model sends belongs to that user.
modelContext is visible to the model and in audit events, so keep secrets out of it.
Securing the tool token
- Don’t reuse the ordinary host login JWT. Use a separate signing key/token namespace with its own issuer/audience, a short expiry, and the narrowest operation scope.
- Your ordinary host endpoints must reject the tool token, and the tool server must reject login tokens. Test both, including account/password/admin APIs.
- Check current user status and record ownership on every call, so a disabled or downgraded user loses access immediately.
- Tool allowlists and approvals limit what the agent tries; only your authorization limits what it can do.
requireApproval: true on the server, or list tool names. See Approvals & questions.
OpenAPI Integration
Publish a focused OpenAPI 3.0 or 3.1 document with only the operations the agent may use. Preview it, choose the operations, and install the revision you reviewed:Reachability
Tool servers and APIs must be public HTTPS URLs. You can pass an OpenAPI document inline (kind: "openapi_document"), but the API itself must still be reachable. For local development, tunnel only the tool endpoint, never the whole app: a tunnel to your dev app’s port (cloudflared tunnel --url http://localhost:3000) publishes every page, including sign-in and admin. If the tool server runs on its own port, tunnel that port; otherwise run a small forwarder that passes only the tool path and tunnel its port (copy-paste snippet under “Local development” in references/tools-and-auth.md of the client skill).
Keep the tool surface small
Tool schemas cost prompt tokens on every turn. UseallowedTools to expose only what you need, and gate writes with approvals.