Give the agent your data

The agent reaches your product through tools you expose. OpenGeni calls them on the agent’s behalf; your API authorizes every call. There are two main ways to do it:

Use	When
Per-session MCP server	The agent should act as the signed-in user, with a short-lived token you mint for each session
OpenAPI Integration	You already have an HTTP API. Describe the operations the agent may use; OpenGeni compiles them into tools for a workspace

Either way, the tool must also be selected in the session’s tools. Nothing reaches the agent unless you select it.

Per-session MCP server with a per-user token

Allow users to attach an MCP server

Add mcp_servers:attach to the permissions you grant during onboarding.

Attach and select the server when creating the session

const acme = (token: string) => ({ id: "acme", headers: { Authorization: `Bearer ${token}` } });

await og.asUser(user.id, { source }).createSession(workspaceId, {
  initialMessage,
  idempotencyKey,
  mcpServers: [
    {
      ...acme(await mintUserToken(user)),
      url: "https://api.acme.com/mcp",
      allowedTools: ["get_ticket", "update_ticket"],
    },
  ],
  tools: [{ kind: "mcp", id: "acme" }], // required: the server must also be selected
  firstPartyMcpTools: [],
  sandboxBackend: "none",
});

Header values are encrypted at rest and never returned in responses or events.

Rotate the token on every message

beforeForwardMessage runs on your server before each message the browser sends. Return a fresh token and any per-message context:

createSessionProxyHandler(og, {
  resolve,
  beforeForwardMessage: async (_message, { user }) => ({
    mcpCredentialUpdates: [acme(await mintUserToken(user))],
    modelContext: `Today is ${new Date().toISOString().slice(0, 10)}. Current page: tickets.`,
  }),
});

OpenGeni applies the update atomically as the message is accepted. The browser can never send credential updates itself.

Authorize every call in your MCP server

Validate the token and derive the tenant and user from it. Never trust a tenant or record id the model supplies without checking it belongs to that user.

Make the token outlive one turn: agents can work for many minutes. modelContext is visible to the model and in the session’s audit events, so never put secrets in it. To require human approval before a tool runs, set requireApproval: true on the server, or list specific tool names. See Approvals & questions.

OpenAPI Integration

If your product already has an HTTP API, 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 exact revision you reviewed:

const source = { kind: "openapi" as const, url: "https://api.acme.com/agent-openapi.json" };
const preview = await og.previewApiIntegration(workspaceId, { source, connectionId });
const installed = await og.installApiIntegration(workspaceId, {
  source,
  connectionId, // the encrypted credential the integration calls your API with
  expectedRevisionId: preview.revisionId,
  expectedContentSha256: preview.contentSha256,
  instanceKey: "acme-api",
  allowedTools: ["getTicket", "updateTicket"],
});
// Persist installed.serverId, then select it per session:
// tools: [{ kind: "mcp", id: installed.serverId }]

Integrations belong to a workspace, so every session in that workspace can select them. They are the right fit for background agents, which cannot carry a per-session MCP server. GraphQL endpoints and workspace-wide MCP connections are also supported.

Reachability

MCP server URLs and OpenAPI documents must be public HTTPS URLs the OpenGeni deployment can reach. For local development, expose your server with a tunnel such as cloudflared tunnel --url http://localhost:4101 or ngrok http 4101.

Keep the tool surface small

Tool schemas cost prompt tokens on every turn. Use allowedTools to expose only what the use case needs, and keep writes approval-gated unless you want the agent to act on its own.

Using a coding agent? The opengeni-client skill covers this.

Get started

Build

Concepts

Guides

Reference

Examples

Further reading

Give the agent your data

Per-session MCP server with a per-user token

OpenAPI Integration

Reachability

Keep the tool surface small

​Per-session MCP server with a per-user token

​OpenAPI Integration

​Reachability

​Keep the tool surface small

Per-session MCP server with a per-user token

OpenAPI Integration

Reachability

Keep the tool surface small