MCP Forge

View Markdown

Local admin portal.mdDownload .md

# The admin portal

Runku includes a local operator portal served by the same `runku` process at:

```
http://<host>:<port>/portal/
```

It's operator-facing only. Nothing about it is reachable by an MCP
agent, and it never appears in `tools/list` — it's a separate HTTP
surface (`/reports/*` + `/portal/`) mounted alongside `/mcp/*`.

## Getting in

The portal's static shell (`/portal/`) always loads, regardless of
`auth.enabled` — a browser has to be able to load the page before a
human has anything to authenticate with. Everything it *fetches*
(`/reports/*`) is protected exactly like `/mcp` when auth is on:

- **`auth.enabled: false`** — the dashboard renders immediately, no
  login step.
- **API keys only** — a token-paste form gates the dashboard; enter a
  key created with `runku auth apikey create`.
- **OIDC configured with `portal_client_id`** — a "Log in with SSO"
  button redirects to your provider's real login page (Authorization
  Code + PKCE, entirely client-side, no client secret involved since
  it's a public browser client). The token-paste fallback is always
  available too, even with SSO configured.

Logging out via SSO performs a real RP-initiated logout against the
provider (not just clearing the local token) — so switching test
identities doesn't require an incognito window.

## The six tabs

| Tab | What it shows |
|---|---|
| **Dashboard** | Summary cards (allowed / blocked / error / pending counts), a connector/identity filter, and charts (call volume over time, tool-usage breakdown, latency). Clicking a verdict card jumps to Audit Log pre-filtered to it. |
| **Audit Log** | The full, searchable audit trail — text search plus verdict/tool/identity filters and a from/to time range (with a live "Realtime" toggle). Click any row for a slide-in panel with the entry's full JSON. |
| **Playground** | Pick a connector and a tool, get a JSON editor pre-filled with a schema-derived sample payload, and call it directly from the browser — invokes the real tool handler in-process, so it's a genuine call (audited, policy-checked), not a mock. |
| **MCP Docs** | Auto-generated documentation for every tool the connected connectors currently expose — the same JSON Schemas an MCP client sees, rendered for a human. |
| **Tool Analysis** | Runtime metrics — CPU, memory, disk, and audit-database size, current and historical. |
| **Agent Config** | The full effective policy and permission picture: every connector's exposed tables, columns and mutations, every identity's role, and any read-only or per-table restriction. Tables that exist but are not exposed remain visibly marked as unavailable. |

Nothing sensitive ever reaches the browser through any of these: no
DSNs, no API-key hashes, no OAuth2 client secrets, and masked-column
values never appear even in the Playground or Audit Log — the same
discipline that applies to the audit log everywhere else applies here,
since the portal is reading the same data.

The portal is available automatically whenever the service is running; no
separate installation or web server is required.

The admin portal

Runku includes a local operator portal served by the same runku process at:

http://<host>:<port>/portal/

It's operator-facing only. Nothing about it is reachable by an MCP agent, and it never appears in tools/list — it's a separate HTTP surface (/reports/* + /portal/) mounted alongside /mcp/*.

Getting in

The portal's static shell (/portal/) always loads, regardless of auth.enabled — a browser has to be able to load the page before a human has anything to authenticate with. Everything it fetches (/reports/*) is protected exactly like /mcp when auth is on:

auth.enabled: false — the dashboard renders immediately, no login step.
API keys only — a token-paste form gates the dashboard; enter a key created with runku auth apikey create.
OIDC configured with portal_client_id — a "Log in with SSO" button redirects to your provider's real login page (Authorization Code + PKCE, entirely client-side, no client secret involved since it's a public browser client). The token-paste fallback is always available too, even with SSO configured.

Logging out via SSO performs a real RP-initiated logout against the provider (not just clearing the local token) — so switching test identities doesn't require an incognito window.

The six tabs

Tab	What it shows
Dashboard	Summary cards (allowed / blocked / error / pending counts), a connector/identity filter, and charts (call volume over time, tool-usage breakdown, latency). Clicking a verdict card jumps to Audit Log pre-filtered to it.
Audit Log	The full, searchable audit trail — text search plus verdict/tool/identity filters and a from/to time range (with a live "Realtime" toggle). Click any row for a slide-in panel with the entry's full JSON.
Playground	Pick a connector and a tool, get a JSON editor pre-filled with a schema-derived sample payload, and call it directly from the browser — invokes the real tool handler in-process, so it's a genuine call (audited, policy-checked), not a mock.
MCP Docs	Auto-generated documentation for every tool the connected connectors currently expose — the same JSON Schemas an MCP client sees, rendered for a human.
Tool Analysis	Runtime metrics — CPU, memory, disk, and audit-database size, current and historical.
Agent Config	The full effective policy and permission picture: every connector's exposed tables, columns and mutations, every identity's role, and any read-only or per-table restriction. Tables that exist but are not exposed remain visibly marked as unavailable.

Nothing sensitive ever reaches the browser through any of these: no DSNs, no API-key hashes, no OAuth2 client secrets, and masked-column values never appear even in the Playground or Audit Log — the same discipline that applies to the audit log everywhere else applies here, since the portal is reading the same data.

The portal is available automatically whenever the service is running; no separate installation or web server is required.