Skip to content
SavvyTechiesKeycloak SaaS Docs

MCP server (connect an AI agent)

The MCP server exposes your workspace to any Model Context Protocol client. It’s the same scope-enforced tool registry the in-console assistant uses — so an external agent can create realms, add SSO/federation providers, register apps, manage users, set branding, and more, all through a standard protocol.

How scope works (security)

Section titled “How scope works (security)”

Every request must carry your bearer token in the Authorization header. Scope is derived per request from that verified token — never from the tool arguments — so a client can only ever do what your account is allowed to do. Operators can target any realm; a tenant admin is limited to the realms their account owns.

Connect a client

Section titled “Connect a client”
  1. Get an access token for your account (the console MCP tab has a Copy my current access token button; for a long-lived client use a service account — ask us).
  2. Point your MCP client at the endpoint with the token in the Authorization header.
  3. List tools and call them — mutations stage a dry-run and require an explicit apply, exactly like the assistant.

Example client config

Section titled “Example client config”
{
  "mcpServers": {
    "savvytechies": {
      "type": "http",
      "url": "https://mcp.savvytechies.com/",
      "headers": { "Authorization": "Bearer <YOUR_ACCESS_TOKEN>" }
    }
  }
}

Guide your agent with CLAUDE.md

Section titled “Guide your agent with CLAUDE.md”

Grab a ready-made CLAUDE.md from the console MCP tab (Download CLAUDE.md) and drop it into your project. It gives Claude the platform context, the safe-change rules (dry-run → confirm, never print secrets), and copy-ready task recipes — so a tenant admin gets guided, safe usage instead of trial-and-error. Keep it in your repo root next to where you run Claude.

Testing the connection

Section titled “Testing the connection”
  1. MCP Inspector (easiest): npx @modelcontextprotocol/inspector → Transport Streamable HTTP, URL https://mcp.savvytechies.com/, header Authorization: Bearer <token>. Browse + invoke tools.
  2. Claude Desktop / Claude Code: use the config above, then ask “list my realms.”
  3. curl smoke test:
    Terminal window
    curl -s https://mcp.savvytechies.com/ -H "Authorization: Bearer $TOKEN" \
      -H 'Content-Type: application/json' -H 'Accept: application/json' \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
    No token returns 401; a valid token lists the tools.

What you can call

Section titled “What you can call”

The MCP surface mirrors the assistant’s commands:

  • Realms — create, inspect, change.
  • SSO & federation — list and add identity providers (Google, Facebook, OIDC, SAML).
  • Applications — register OIDC and SAML clients, manage redirect URIs.
  • Users & access — create users, reset passwords, assign roles/groups.
  • Branding & custom domains, support/incidents, and usage reads.

Safety model

Section titled “Safety model”
  • Two-phase mutations — a change first returns a dry-run proposal; it only runs after an explicit apply. Reads run immediately.
  • Secrets never transit the prompt — e.g. an IdP client secret is supplied out-of-band and referenced, never passed as an argument.
Section titled “Related”