MCP Server

The Olly MCP (Model Context Protocol) server gives AI assistants — Claude, Cursor, and any other MCP-compatible client — direct programmatic access to Olly's infrastructure. Instead of copy-pasting API responses or reading logs manually, the assistant can query services, inspect traces, run database counts, and manage users directly through structured tool calls.

Connection

Environment	Endpoint
Production	`https://mcp.olly.theflywheel.in/mcp`
Local (Tilt)	`http://localhost:3100/mcp`

The server is stateless: each HTTP request gets a fresh McpServer instance. There is no session state between calls.

Claude Code Configuration

Add the following to your claude_mcp_config.json (or the MCP config block in Claude Desktop / Claude Code settings):

json

{
  "mcpServers": {
    "olly": {
      "type": "http",
      "url": "https://mcp.olly.theflywheel.in/mcp"
    }
  }
}

For local development, swap the URL to http://localhost:3100/mcp. The Tilt dev environment auto-reloads the server when source files in mcp/server/src/ change.

Available Tools

Service Health

Tool	Description
`health_check`	Check health of one or all Olly services (claims, eligibility, enrollment, billing, provider, notifications, policy-admin, triage, care, consent, document-service, member-portal-api, group-scheme-service, broker-api). Omit the `service` argument to check all 14 at once.

Domain Operations

These tools call the running Olly microservices directly over their internal HTTP APIs.

Claims

Tool	Description
`claims_list`	List claims with optional filters: `status`, `memberPartyId`, `policyId`
`claims_get`	Get a claim by locator (e.g. `CLM-2026-000001`)
`claims_submit`	Submit a new insurance claim
`prior_auth_submit`	Submit a prior authorization request
`prior_auth_list`	List prior authorization requests
`prior_auth_review`	Move a prior authorization to `PENDING_REVIEW` status
`prior_auth_decide`	Approve or deny a prior authorization

Eligibility

Tool	Description
`eligibility_check`	Check eligibility for a member on a service date
`member_coverage_list`	List coverage records for a member party locator
`member_accumulators_get`	Get accumulators (deductibles, out-of-pocket) for a member

Enrollment

Tool	Description
`quote_create`	Create a new insurance quote
`quote_get`	Get a quote by locator
`quote_bind`	Issue (bind) a quote to create a policy
`policy_get`	Get a policy by locator
`policy_list`	List policies, filtered by `accountId` or `brokerLocator`

Billing

Tool	Description
`invoice_list`	List invoices with optional filters: `account_id`, `status`
`invoice_get`	Get an invoice by locator
`payment_record`	Record a payment against an invoice
`ledger_get`	Get ledger entries for an account or policy

Provider

Tool	Description
`provider_search`	Search providers by specialty or network status
`provider_get`	Get a provider by locator
`credentialing_submit`	Submit a credentialing application for a provider

Notifications

Tool	Description
`notification_preferences_get`	Get notification preferences for a party
`notification_preferences_update`	Update notification channel and opt-out settings for a party

Policy Admin

Tool	Description
`product_list`	List insurance products, filtered by status
`product_get`	Get a product by locator
`party_get`	Get a party (individual or organization) by locator
`party_list`	List parties with optional type and search filters
`ruleset_list`	List rulesets for a product version

Triage

Tool	Description
`triage_start`	Start a triage session for a member (requires consent)
`triage_respond`	Respond to a triage question to advance the session
`triage_get`	Get a triage session by locator

Care

Tool	Description
`care_episode_create`	Create a care episode for a member
`care_episode_get`	Get a care episode by locator
`care_appointment_book`	Book an appointment within a care episode
`care_appointments_list`	List appointments for a care episode

Group Schemes

Tool	Description
`scheme_create`	Create an employer group scheme
`scheme_get`	Get a group scheme by locator
`scheme_list`	List group schemes, optionally filtered by employer
`scheme_members_list`	List members of a group scheme

Broker

Tool	Description
`broker_portfolio_get`	Get the broker's portfolio of policies (requires broker JWT)
`broker_commissions_list`	List broker commissions (requires broker JWT)
`broker_authority_get`	Get the delegated authority configuration for a broker

Tool	Description
`consent_get`	Get consent records for a party
`consent_record`	Record or update a consent decision for a party

Documents & Member Portal

Tool	Description
`document_get`	Get a document by locator (returns PDF metadata or content URL)
`member_coverage_get`	Get the authenticated member's active coverage summary (requires member JWT)
`member_claims_list`	Get the authenticated member's claims (requires member JWT)

Infra / Kubernetes

Tool	Description
`list_pods`	List Kubernetes pods in a namespace (default: `services`)
`get_nodes`	List all EKS cluster nodes with instance type and ready status
`kafka_lag`	Get Kafka consumer group lag for Olly topics; omit `group` to list all groups

Observability / Traces

Tool	Description
`trace_get`	Retrieve a specific trace by ID from Grafana Tempo
`trace_search`	Search traces in Grafana Tempo by service name, minimum duration, or tag
`logs_query`	Query Grafana Loki for logs from a service with an optional LogQL filter
`alerts_list`	List active Grafana alerts (default: firing)

Data / Aurora

Tool	Description
`db_counts`	Get live row counts for all tables in a service schema (read-only)
`cache_stats`	Get ElastiCache Valkey memory and key statistics

Auth / Users

Tool	Description
`user_search`	Search for users in a Keycloak realm (`olly-members`, `olly-providers`, `olly-internal`)
`user_roles`	Get roles assigned to a user in a Keycloak realm

Architecture

AI Client (Claude / Cursor)
        │  HTTP POST (StreamableHTTP)
        ▼
https://mcp.olly.theflywheel.in/mcp
        │
        ▼
   MCP Server (Node 22, TypeScript)
   @modelcontextprotocol/sdk
   Fresh McpServer per request (stateless)
        │
        ├── health.ts       → /healthz on each service
        ├── domain.ts       → internal service HTTP APIs
        ├── k8s.ts          → kubectl (EKS)
        ├── traces.ts       → Grafana Tempo + Loki + Alertmanager
        ├── aurora.ts       → Aurora PostgreSQL (read-only) + ElastiCache
        └── users.ts        → Keycloak Admin API

The server uses the StreamableHTTP transport from @modelcontextprotocol/sdk. Each incoming request creates a new McpServer, registers all tools, handles the request, and is discarded. This means the server scales horizontally without any shared state.

In the Tilt dev environment the server is rebuilt and restarted automatically whenever any file under mcp/server/src/ changes.

Adding New Tools

Pick or create the right file — tool files live under mcp/server/src/tools/:
- services/health.ts — service health
- services/domain.ts — service domain operations
- infra/k8s.ts — Kubernetes / infrastructure
- observability/traces.ts — Tempo, Loki, Grafana
- data/aurora.ts — database and cache
- auth_tools/users.ts — Keycloak / users
Register the tool — call server.tool(name, description, schema, handler) inside the file's register*Tools(server) function using Zod for input validation.
Wire it up — if you created a new file, import its register*Tools function in mcp/server/src/index.ts and call it with the app instance.
Test locally — Tilt will hot-reload the server. Connect your MCP client to http://localhost:3100/mcp and invoke the new tool.

MCP Server ​

Connection ​

Claude Code Configuration ​

Available Tools ​

Service Health ​

Domain Operations ​

Claims ​

Eligibility ​

Enrollment ​

Billing ​

Provider ​

Notifications ​

Policy Admin ​

Triage ​

Care ​

Group Schemes ​

Broker ​

Consent ​

Documents & Member Portal ​

Infra / Kubernetes ​

Observability / Traces ​

Data / Aurora ​

Auth / Users ​

Architecture ​

Adding New Tools ​