Skip to main content
Northstar is a fictional customer-support app that shows the full integration. Use it as a working reference.

What it shows

  • The embed. createSessionProxyHandler at /api/opengeni/*, with OpenGeniProvider and SessionConversation in a panel beside the ticket. Toggle the Opengeni switch to compare with and without the agent.
  • Product tools. The agent reads and updates tickets through Northstar’s MCP server (get_ticket, get_customer, update_ticket, add_internal_note). Changes show up in the app immediately, for the visitor whose agent made them.
  • Custom tool rendering. Tool calls render as ticket and customer cards through a toolRegistry.
  • Branding. Compact density and Northstar colors through --og-* tokens.

Run it

You need Bun, a repository checkout, a shared workspace used only by the demo, an organization API key, and a public HTTPS tunnel for the MCP server. Create the key on an Admin service account with Access: Custom granting exactly workspace:read, sessions:create, sessions:read, sessions:control, mcp_servers:attach, and members:manage, available only in the demo workspace. Set a workspace budget to cap what visitors can spend. When the Opengeni server accepts per-task usage limits (sessionUsageLimits.enabled in GET /v1/config/client), each run also carries a $1.00 usage limit; otherwise runs start without one.
In a second terminal, expose the MCP port (or set OPENGENI_DEMO_MCP_URL to any public HTTPS URL that reaches port 4101):
In a third terminal, start the UI and open http://127.0.0.1:3101:

Where to look

The demo uses one fixed user and pre-approved tools. It keeps anonymous browsers apart with a signed visitor cookie: authorizeSession lets each browser reach only the sessions it started, and each browser works on its own copy of the tickets. Each session’s MCP server carries a signed visitor header set by the server, so the agent’s tools read and change only that visitor’s copy. Each run gets only the Northstar tools (capabilities: { from: "none", skills: false }), and runs, messages, proxied reads, writes, and open streams are rate-limited per visitor, per client network, and demo-wide. A real app authenticates users in resolve and checks CSRF in authorizeMutation. View the source on GitHub.