# Okta MCP server — remote deployment for Claude.ai

Runs Okta's stdio-only [`okta-mcp-server`](https://github.com/okta/okta-mcp-server)
as a remote, OAuth-protected Streamable HTTP connector on Google Cloud Run, so
it can be used from Claude.ai over the internet.

A thin [FastMCP](https://gofastmcp.com) wrapper (`wrapper/server.py`) does three
things: bridges the stdio server to Streamable HTTP, enforces Okta OAuth on the
front door (token introspection), and adds a few native Admin API tools the
upstream package can't currently serve.

See [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) for the full Okta + Cloud Run +
Claude.ai setup and troubleshooting.

## What this adds over the upstream package

The base [`okta-mcp-server`](https://github.com/okta/okta-mcp-server) is a
stdio-only server meant to run locally under Claude Desktop / an IDE. This repo
turns it into a shared, internet-reachable connector and fills some gaps:

- **Remote transport.** A FastMCP wrapper (`wrapper/server.py`) proxies the
  stdio server and re-exposes it over Streamable HTTP on `0.0.0.0:$PORT`, which
  is what Claude.ai's remote connectors speak. Upstream offers no HTTP mode.
- **OAuth front door.** Every request is authenticated against your Okta org
  authorization server via RFC 7662 token introspection, with the OAuth
  discovery metadata Claude.ai expects. Access is gated by assignment to the
  `Claude.ai Connector` app.
- **Headless backend auth.** The proxied server runs with the browserless
  Private Key JWT flow (not the interactive device flow), suitable for a
  container.
- **Cloud Run deployment.** `Dockerfile`, `deploy/deploy.sh` (gcloud) and
  `terraform/` provision the service, a least-privilege runtime service
  account, and Secret Manager wiring; `docs/DEPLOYMENT.md` is the runbook.
- **Native Admin API tools.** Application search, assignment listing, group
  assignment management, and provisioning-feature management — capabilities the
  base package lacks or can't serve reliably. They return raw JSON (working
  around a bug where the upstream SDK models reject some app subtypes) and
  surface Okta error bodies instead of raising. Listed below.

## Tools

All the upstream `okta-mcp-server` tools are exposed via the proxy, filtered by
`OKTA_SCOPES`. In addition, the wrapper adds these **native tools** — thin
wrappers over the Okta Management API that return raw JSON (bypassing the
upstream SDK models, which reject some app subtypes). On an Okta error they
return the error body (e.g. `E0000007`, `E0000006`) rather than raising.

Native tools are not part of the upstream package, so they do **not** appear in
the backend's `get_scope_status`.

| Tool | Okta endpoint | Scope |
|---|---|---|
| `find_applications` | `GET /api/v1/apps` | `okta.apps.read` |
| `list_application_users` | `GET /api/v1/apps/{id}/users` | `okta.apps.read` |
| `list_application_group_assignments` | `GET /api/v1/apps/{id}/groups` | `okta.apps.read` |
| `list_application_features` | `GET /api/v1/apps/{id}/features` | `okta.apps.read` |
| `assign_group_to_application` | `PUT /api/v1/apps/{id}/groups/{groupId}` | `okta.apps.manage` |
| `remove_group_from_application` | `DELETE /api/v1/apps/{id}/groups/{groupId}` | `okta.apps.manage` |
| `confirm_remove_group_from_application` | `DELETE /api/v1/apps/{id}/groups/{groupId}` | `okta.apps.manage` |
| `update_application_feature` | `PUT /api/v1/apps/{id}/features/{name}` | `okta.apps.manage` |

`remove_group_from_application` is destructive (it can trigger deprovisioning),
so it asks for confirmation via elicitation and falls back to
`confirm_remove_group_from_application` (requires `confirmation="REMOVE"`) when
the client can't show a prompt.

## Deploy

```bash
./deploy/deploy.sh          # first pass
PUBLIC_BASE_URL="https://<run.app-url>" ./deploy/deploy.sh   # second pass
```

Layout: `wrapper/server.py` (the wrapper), `Dockerfile`, `requirements.txt`,
`deploy/deploy.sh` (gcloud) or `terraform/` (IaC), `docs/DEPLOYMENT.md` (runbook).

## Licence & attribution

Licensed under the [Apache License 2.0](LICENSE), © 2026 Rittman Analytics
Limited.

This is an independent wrapper, not a fork. It builds on Okta's
[`okta-mcp-server`](https://github.com/okta/okta-mcp-server) — also Apache 2.0 —
which it installs as a dependency and runs as a subprocess (see
`requirements.txt`); none of its source is copied into this repo. See
[`NOTICE`](NOTICE) for details.