Okta Max
← Back to Okta Max AI assistant

Set up the Claude assistant server

Deploy the example server to your own infrastructure and give every admin Claude for the tougher, multi-step questions. You host it, you choose the model, and each admin signs in with their own Okta identity, so Okta enforces their role on every lookup.

  1. What you'll need

    • Node.js and uv (or just Docker)
    • A model: an Anthropic API key, or Claude on Amazon Bedrock in your AWS account
    • A super admin, once, to create the Okta OIDC app
    • The extension's ID, shown on chrome://extensions

  2. Clone the repo

    git clone https://github.com/forevanyeung/oktamax.git && cd oktamax
npm install
cp server/.env.example server/.env   # set OKTA_ORG_URL

  3. Create the Okta OIDC app

    One command creates a PKCE app with read-only Okta API scopes, sets the redirect URIs, optionally assigns it to a group, and prints the client ID. Add --server so admins can also use the org's MCP server from their own AI tools. 

    OKTA_API_TOKEN=... npm run create-okta-app -w @oktamax/server -- \
  <extension-id> --group "Okta Admins" --server https://oktamax.example.com

    Put the printed OKTA_CLIENT_ID in server/.env, or list several orgs in OKTA_ORGS. Then give the app an authentication policy your admins' console sign-in already satisfies, so sign-in stays silent. The README has the manual steps.

  4. Choose a model

    Set ANTHROPIC_API_KEY in server/.env to use Anthropic's API. Without it, the server uses Bedrock with the standard AWS credential chain and AWS_REGION. MODEL_ID picks the model.

  5. Start it

    npm run dev:server        # http://localhost:8787

    Or with Docker, which preinstalls Python and Okta's MCP server:

    docker build -f server/Dockerfile -t oktamax-server .
docker run -p 8787:8787 --env-file server/.env oktamax-server

  6. Connect your admins

    Each admin picks Chat server in the popup and enters its URL. Or set it for everyone in the Google Admin console under Devices › Chrome › Apps & extensions, in Okta Max's Policy for extensions: 

    { "chatServerUrl": "https://oktamax.example.com" }

    Intune, Jamf and Group Policy can set the same key. See admin-managed policies for details.

  7. Optional: add Okta to your AI tools

    Admins can add their org's read-only MCP server to any MCP client that supports OAuth. They sign in with Okta on first use. 

    claude mcp add --transport http okta-acme \
  https://oktamax.example.com/mcp/acme.okta.com

Bring your own model or server

A different model

The example server is built on the Vercel AI SDK, so the model is created in one place, server/src/index.ts. Swap in any AI SDK provider, including OpenAI-compatible endpoints like a local Ollama or vLLM, and keep everything else. The model needs to support tool calls.

Your own chat server

The extension speaks a small HTTP API, not the OpenAI chat API, so it can't point at a bare LLM endpoint. To replace the server, implement these routes and stream replies in the AI SDK's UI message stream format (server-sent events): 

GET  /api/config                orgs and their OIDC client IDs
GET  /api/chats/:id             chat history (404 if new)
POST /api/chats/:id/messages    send a message, stream the reply
GET  /api/chats/:id/stream      resume an in-flight reply (204 if none)
POST /api/chats/:id/stop        stop the reply

Requests carry the admin's Okta access token as a Bearer token, and the org in an X-Okta-Org header. Each org's /mcp/<org host> endpoint is a standard MCP server.