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
Dev	https://mcp.dev.hiolly.com/mcp
Local (Tilt)	http://localhost:3100/mcp

Stateless transport

Each HTTP request gets a fresh McpServer instance. There is no session state between calls - callers cannot rely on prior-turn context inside the server.

Claude Code Configuration

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

{
  "mcpServers": {
    "olly": {
      "type": "http",
      "url": "https://mcp.dev.hiolly.com/mcp"
    }
  }
}

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

Consent

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

Tool	Description
list_pods	List the running Olly service containers (dev is docker-compose, not Kubernetes; the k8s-shaped tools target the GKE production cluster only).
get_nodes	List cluster nodes with instance type and ready status. Applies to the GKE production target; dev has no cluster.
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

Tool	Description
db_counts	Get live row counts for all tables in a service schema (read-only). Backed by the single Postgres instance on dev-2.
cache_stats	Get 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.dev.hiolly.com/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 (GKE production target only; dev is docker-compose)
        ├── traces.ts       → Grafana Tempo + Loki + Alertmanager
        ├── postgres.ts     → Postgres (read-only) + Valkey
        └── 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

1. 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 (GKE production target only)
   • observability/traces.ts - Tempo, Loki, Grafana
   • data/postgres.ts - database (Postgres) and cache (Valkey)
   • auth_tools/users.ts - Keycloak / users

2. Register the tool - call server.tool(name, description, schema, handler) inside the file's register*Tools(server) function using Zod for input validation.

3. 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.

4. Test locally - Tilt will hot-reload the server. Connect your MCP client to http://localhost:3100/mcp and invoke the new tool.