Skip to main content
Glama
GRACC MCP Server

GRACC MCP Server

Official

GRACC MCP Server

Docker License

Read-only Model Context Protocol (MCP) server for GRACC, the OSG accounting system.

This server gives MCP-compatible AI clients safe access to public GRACC accounting data through the documented public OpenSearch-compatible endpoint:

  • https://gracc.opensciencegrid.org/q

The implementation is intentionally conservative:

  • read-only only

  • default index alias gracc.osg.summary

  • aggregation-first workflows

  • hard validation and safety caps

  • standards-compliant MCP tool definitions

  • portable STDIO-first design, with optional Streamable HTTP

Quick Start

Run the published image:

docker run --rm -p 3333:3333 ghcr.io/opensciencegrid/gracc-mcp-server:latest

Then point any MCP client that supports Streamable HTTP at http://localhost:3333/mcp. For example, with Claude Code:

claude mcp add --transport http gracc http://localhost:3333/mcp

To run without a network listener, build from source and register the server over STDIO instead; see Setup and Other MCP Client Notes.

Questions to try:

  • "Which VOs used the most core hours in October 2026?"

  • "Show weekly GPU hours for the last three months."

  • "How many jobs did LIGO run last week, and how many core hours did they use?"

More examples are in examples/prompts.md. A good first call for a new client is list_dimensions, which returns the valid filter, grouping and metric ids.

Related MCP server: openai-usage-mcp

What GRACC Is

GRACC is the Open Science Grid accounting system. It collects and summarizes usage data and exposes public read-only query access for analytics. The GRACC docs explicitly document the public query endpoint and show aggregation examples over fields such as EndTime, VOName, ResourceType, CoreHours, and Njobs.

What This Server Does

This MCP server wraps a small, safe subset of that public query surface into model-friendly tools:

  • list_dimensions

  • query_usage_summary

  • top_n_entities

  • time_series_usage

  • get_schema_notes

  • run_safe_query

The server is designed for LLM tool use, not for raw admin access or dashboard mirroring.

Supported Tools

list_dimensions

Lists supported filter fields, grouping fields, date fields, and metrics.

Good first call for a client that needs to discover valid arguments before issuing analytical queries.

query_usage_summary

Returns aggregate usage metrics over a required time range with optional exact-match filters.

Example use cases:

  • total core_hours for vo_name=ligo

  • total job_count for resource_type=Payload

  • total cpu_duration_seconds for a project over a week

top_n_entities

Ranks the top N values for a supported dimension using a selected metric.

Example use cases:

  • top VOs by core_hours

  • top projects by job_count

  • top sites by wall_duration_seconds

time_series_usage

Returns a date histogram over a required time range and metric.

Supported intervals:

  • day

  • week

  • month

get_schema_notes

Returns concise notes, caveats, and source references derived from public GRACC docs and observed public mappings.

run_safe_query

Expert tool for constrained raw _search access. It can be turned off with GRACC_ENABLE_SAFE_QUERY=false.

The caller's JSON is never forwarded. The server validates each part and builds a fresh request from it, so any key it does not recognize is rejected rather than passed through to GRACC.

Requirements:

  • query is required and must contain a range on EndTime or @timestamp with both a lower (gte/gt) and upper (lt/lte) bound, either as the top-level query or inside bool.filter. A range inside must_not does not count.

  • The bounded range must be at most GRACC_MAX_RANGE_DAYS long.

  • Date values must be strict ISO 8601 (2026-04-01 or 2026-04-01T12:00:00Z). Epoch numbers and date math such as now-7d are rejected.

It only allows:

  • allowlisted index selection

  • allowlisted fields (ids such as vo_name are resolved to field names such as VOName)

  • term, terms (at most 25 values), range, and bool with filter/must_not (at most 3 levels deep, 32 clauses total)

  • terms aggregations with field, size (at most GRACC_MAX_TOP_N), and order (_count, _key, or a child metric aggregation)

  • date_histogram aggregations with field (a date field that has a bounded range in the query), calendar_interval (day, week, month), and time_zone

  • sum (metric fields only) and value_count aggregations with field

  • at most 10 aggregations, nested at most 2 deep, with an estimated total of at most 10,000 buckets

  • size defaults to 0; when hits are requested, _source is limited to allowlisted fields

It rejects:

  • writes, updates, deletes, and endpoints other than _search

  • scripts anywhere, including inside aggregations

  • query_string and any other unsupported query operator

  • aggregation options such as extended_bounds, min_doc_count, shard_size, include, exclude, and missing

  • result payloads above GRACC_MAX_RESULT_BYTES

Supported Indices

The server queries only this index alias by default:

  • gracc.osg.summary

Observed public mappings on 2026-04-22 showed backing summary indices such as yearly gracc.osg.summary4-* indices, but the server intentionally targets the documented alias rather than those backing indices directly.

Supported Fields And Metrics

Primary dimensions:

  • vo_name -> VOName

  • reportable_vo_name -> ReportableVOName

  • project_name -> ProjectName

  • resource_type -> ResourceType

  • common_name -> CommonName

  • site_name -> SiteName

  • oim_site -> OIM_Site

  • resource_group -> OIM_ResourceGroup

  • submit_host -> SubmitHost

  • probe_name -> ProbeName

  • end_time -> EndTime

  • timestamp -> @timestamp

Primary metrics:

  • job_count -> sum of Njobs

  • core_hours -> sum of CoreHours

  • wall_duration_seconds -> sum of WallDuration

  • cpu_duration_seconds -> sum of CpuDuration

  • cpu_user_seconds -> sum of CpuDuration_user

  • cpu_system_seconds -> sum of CpuDuration_system

  • processor_count_sum -> sum of Processors

  • gpu_hours -> sum of GPUHours

  • gpu_count_sum -> sum of GPUs

Setup

Requirements

  • Node.js 20.11+

  • npm 10+

Install

npm install

Build

npm run build

Test

npm run test

Optional live test against the public endpoint:

GRACC_LIVE_TESTS=1 npm run test:live

Run Via STDIO

For local MCP clients that spawn the server as a subprocess:

npm run dev:stdio

Or after building:

npm run start:stdio

Run Via HTTP

Optional stateless Streamable HTTP endpoint:

npm run dev:http

Or after building:

npm run start:http

Default URL:

  • http://127.0.0.1:3333/mcp

Docker Image

Published image: ghcr.io/opensciencegrid/gracc-mcp-server

docker run --rm -p 3333:3333 ghcr.io/opensciencegrid/gracc-mcp-server:latest

The image runs the HTTP transport and listens on 0.0.0.0:3333 (path /mcp). Pass any GRACC_* setting from Configuration with -e, for example -e GRACC_RATE_LIMIT_MAX=60.

To build it yourself:

docker build -t gracc-mcp-server .

GitHub Actions Docker Build

This repository includes a GitHub Actions workflow at .github/workflows/docker.yml.

It does two things:

  • builds the Docker image on every push, pull request, and manual workflow run

  • pushes the image to GitHub Container Registry on pushes to the default branch and on tag pushes

Published image: ghcr.io/opensciencegrid/gracc-mcp-server

Published tags:

  • latest and main on the default branch

  • 1.2.3 and 1.2 when a v1.2.3 git tag is pushed

  • sha-<commit> for every published commit

Pin a sha-<commit> or version tag for deployments rather than latest.

Kubernetes With Kustomize

The manifests under k8s/ are a generic example you can adapt:

  • k8s/base: Deployment, ConfigMap and two ClusterIP Services

  • k8s/overlays/dev: a standalone gracc-mcp namespace using the published image

  • k8s/overlays/nrp: an NRP Nautilus deployment behind the Envoy AI Gateway

OSG's hosted instance is deployed from separate cluster configuration, not from these overlays.

The example deployment runs two containers in one pod:

  • gracc-mcp on port 3333 for the native MCP endpoint

  • mcpo on port 8000 as an optional MCP-to-OpenAPI bridge for Open WebUI and other OpenAPI clients. Remove it if you only need MCP.

Deploy:

kubectl apply -k k8s/overlays/dev

The deployment creates two cluster-internal services:

  • gracc-mcp:3333 -> native MCP endpoint at /mcp

  • gracc-mcp-openapi:8000 -> OpenAPI bridge with docs at /docs

In-cluster URLs:

  • http://gracc-mcp:3333/mcp

  • http://gracc-mcp-openapi:8000/docs

The bundled mcpo sidecar uses the Open WebUI-maintained MCP-to-OpenAPI proxy image:

  • ghcr.io/open-webui/mcpo:main

If you need external access, add your own Ingress, Gateway, or service-type override in an overlay rather than changing the base manifests.

Configuration

Copy .env.example to .env and adjust only if needed.

Important settings:

  • GRACC_BASE_URL

  • GRACC_DEFAULT_INDEX

  • GRACC_ALLOWED_INDICES

  • GRACC_MAX_RANGE_DAYS

  • GRACC_MAX_BUCKETS

  • GRACC_MAX_TOP_N

  • GRACC_MAX_SAFE_QUERY_SIZE

  • GRACC_MAX_RESULT_BYTES

  • GRACC_TIMEOUT_MS

  • GRACC_RETRY_COUNT

  • GRACC_HTTP_HOST

  • GRACC_HTTP_PORT

Public deployment settings:

Variable

Default

Purpose

GRACC_ENABLE_SAFE_QUERY

true

Register the expert run_safe_query tool.

GRACC_TRUST_PROXY

false

Express trust proxy value. Set to the number of proxy hops (usually 1 behind an ingress) so rate limits use the real client IP. Avoid true, which lets clients spoof X-Forwarded-For.

GRACC_RATE_LIMIT_MAX

120

HTTP requests per client IP per window. 0 disables rate limiting.

GRACC_RATE_LIMIT_WINDOW_MS

60000

Rate limit window.

GRACC_MAX_CONCURRENT_UPSTREAM

4

Maximum simultaneous requests to GRACC per process.

GRACC_MAX_QUEUED_UPSTREAM

32

Requests allowed to wait for a slot; beyond this the tool returns a "busy" error.

GRACC_MAX_UPSTREAM_BYTES

1048576

Largest GRACC response the server will read.

GRACC_CACHE_TTL_SECONDS

300

How long identical queries are served from memory. 0 disables the cache.

GRACC_CACHE_MAX_BYTES

33554432

Memory budget for the response cache.

Rate limits, the cache, and the concurrency cap are per process, so with N replicas GRACC can see up to N × GRACC_MAX_CONCURRENT_UPSTREAM concurrent requests. If the server sits behind a gateway that does not forward client IPs, every request shares one rate limit bucket. In that case, raise GRACC_RATE_LIMIT_MAX or set it to 0 and limit at the gateway.

Safety Model

This server is intentionally read-only.

Core protections:

  • only _search is used

  • default index allowlist is explicit

  • no write or admin APIs are implemented

  • required date ranges for analytical tools, in strict ISO 8601 and converted to UTC before they are sent upstream, so JavaScript and OpenSearch cannot disagree about what a date means

  • hard caps on date range, bucket count, top N, and raw query size

  • exact-match filters only in normal tools

  • run_safe_query builds a fresh request from validated parts instead of forwarding the caller's JSON

  • per-IP rate limiting on the HTTP endpoint

  • a process-wide cap on concurrent GRACC requests, with a bounded wait queue

  • identical concurrent queries share one GRACC request, and successful responses are cached briefly

  • GRACC responses are read with a byte cap

  • request timeout; only connection failures and 429/502/503/504 responses are retried, with backoff. Query errors and timeouts are not retried, and a Retry-After longer than 5 seconds is not waited out

  • result payload size cap for run_safe_query

Known Assumptions And Field Caveats

Known assumptions

  • gracc.osg.summary is the authoritative public alias used by this server.

  • EndTime is the default time field because it is used in the public GRACC direct-query examples.

  • CoreHours is used directly from the public mapping instead of being derived.

  • ProjectName, ReportableVOName, OIM_Site, and related fields may already reflect GRACC correction and enrichment stages.

Field caveats

  • @timestamp is available from the public mappings but appears to be ingest-oriented, not job-end-oriented.

  • processor_count_sum is a sum of Processors across matching summary documents, not a distinct hardware inventory count.

  • CommonName may be high-cardinality and is often less useful for broad analytics than VO, project, or site fields. It can also be sensitive from a privacy perspective even though the endpoint is public, so prefer higher-level dimensions where they answer the question.

  • Public field caps showed some legacy non-gracc indices with different field types; this server avoids them.

Open questions

  • Is CommonName the best default "submitter" dimension for every downstream use? Checking GRACC dashboards or asking site stakeholders would settle it.

  • Should dimensions like PayloadSiteName or ExecutePool join the allowlist? Current public dashboards and usage examples would show whether they are needed.

  • If public docs standardize other summary aliases, update GRACC_ALLOWED_INDICES and the schema registry together rather than loosening query validation.

Client Compatibility Notes

MCP-standard behavior

These parts are portable across MCP-compatible clients:

  • tool registration and schemas

  • STDIO transport

  • Streamable HTTP transport

  • JSON result formatting

  • read-only tool behavior

The core server does not depend on Codex-only APIs or prompt conventions.

Client-specific examples

These are examples only:

  • examples/codex/config.toml

  • examples/claude-desktop-config.json

  • examples/prompts.md

  • k8s/ deployment manifests

Different clients may vary in:

  • tool-calling frequency

  • schema strictness

  • argument coercion

  • error rendering

  • support for STDIO vs HTTP transports

To stay portable, this server favors:

  • explicit required dates

  • small enums

  • flat JSON outputs

  • exact-match filters

  • conservative errors

Codex Configuration Example

Sample .codex/config.toml snippet:

[mcp_servers.gracc]
command = "node"
args = ["/absolute/path/to/gracc-mcp/dist/index.js"]
cwd = "/absolute/path/to/gracc-mcp"

See examples/codex/config.toml for a fuller example.

Other MCP Client Notes

Claude Desktop

See examples/claude-desktop-config.json for a STDIO registration example.

Claude Code

Over HTTP, with the server or container running:

claude mcp add --transport http gracc http://localhost:3333/mcp

Over STDIO, after npm run build:

claude mcp add gracc -- node /absolute/path/to/gracc-mcp/dist/index.js

ChatGPT Or Other MCP-Compatible Clients

Use either:

  • STDIO mode pointing to dist/index.js

  • Streamable HTTP mode pointing to http://127.0.0.1:3333/mcp

If a client has strict schema handling, prefer calling list_dimensions first and pass only the returned ids.

Project Layout

.
├── .dockerignore
├── AGENTS.md
├── Dockerfile
├── LICENSE
├── README.md
├── examples/
│   ├── claude-desktop-config.json
│   ├── codex/
│   │   └── config.toml
│   └── prompts.md
├── k8s/
│   ├── base/
│   └── overlays/
├── src/
│   ├── client/
│   ├── config/
│   ├── http/
│   ├── mcp/
│   ├── query/
│   ├── schema/
│   ├── tools/
│   ├── utils/
│   ├── validation/
│   ├── http-server.ts
│   └── index.ts
└── tests/
    ├── fixtures/
    ├── integration/
    ├── live/
    └── unit/

Sources

License

Licensed under the Apache License, Version 2.0.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for exploring US federal spending data via the USAspending.gov API, enabling natural language queries on awards, agencies, recipients, and spending trends.
      12
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for querying OpenAI usage and cost data, including spend summaries, daily breakdowns, month-over-month comparisons, and token usage by model.
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server exposing SLURM, GPFS, Prometheus (node exporter + DCGM GPU metrics) and generic Elasticsearch exploration as diagnostic tools for LLM-based HPC support assistants.
      Apache 2.0
    • F
      license
      B
      quality
      D
      maintenance
      A secure, read-only MCP server that enables AI assistants to inspect transactions, vendor performance, wallet balances, and analytics through validated REST API calls.
      19
      -