GRACC MCP Server
OfficialProvides read-only access to GRACC accounting data through its public OpenSearch-compatible endpoint, enabling validated aggregation queries, top-N rankings, time-series usage summaries, and constrained raw OpenSearch _search requests.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
GRACC MCP Server
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.summaryaggregation-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:latestThen 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/mcpTo 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_dimensionsquery_usage_summarytop_n_entitiestime_series_usageget_schema_notesrun_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_hoursforvo_name=ligototal
job_countforresource_type=Payloadtotal
cpu_duration_secondsfor 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_hourstop projects by
job_counttop sites by
wall_duration_seconds
time_series_usage
Returns a date histogram over a required time range and metric.
Supported intervals:
dayweekmonth
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:
queryis required and must contain arangeonEndTimeor@timestampwith both a lower (gte/gt) and upper (lt/lte) bound, either as the top-level query or insidebool.filter. A range insidemust_notdoes not count.The bounded range must be at most
GRACC_MAX_RANGE_DAYSlong.Date values must be strict ISO 8601 (
2026-04-01or2026-04-01T12:00:00Z). Epoch numbers and date math such asnow-7dare rejected.
It only allows:
allowlisted index selection
allowlisted fields (ids such as
vo_nameare resolved to field names such asVOName)term,terms(at most 25 values),range, andboolwithfilter/must_not(at most 3 levels deep, 32 clauses total)termsaggregations withfield,size(at mostGRACC_MAX_TOP_N), andorder(_count,_key, or a child metric aggregation)date_histogramaggregations withfield(a date field that has a bounded range in the query),calendar_interval(day,week,month), andtime_zonesum(metric fields only) andvalue_countaggregations withfieldat most 10 aggregations, nested at most 2 deep, with an estimated total of at most 10,000 buckets
sizedefaults to0; when hits are requested,_sourceis limited to allowlisted fields
It rejects:
writes, updates, deletes, and endpoints other than
_searchscripts anywhere, including inside aggregations
query_stringand any other unsupported query operatoraggregation options such as
extended_bounds,min_doc_count,shard_size,include,exclude, andmissingresult 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->VONamereportable_vo_name->ReportableVONameproject_name->ProjectNameresource_type->ResourceTypecommon_name->CommonNamesite_name->SiteNameoim_site->OIM_Siteresource_group->OIM_ResourceGroupsubmit_host->SubmitHostprobe_name->ProbeNameend_time->EndTimetimestamp->@timestamp
Primary metrics:
job_count-> sum ofNjobscore_hours-> sum ofCoreHourswall_duration_seconds-> sum ofWallDurationcpu_duration_seconds-> sum ofCpuDurationcpu_user_seconds-> sum ofCpuDuration_usercpu_system_seconds-> sum ofCpuDuration_systemprocessor_count_sum-> sum ofProcessorsgpu_hours-> sum ofGPUHoursgpu_count_sum-> sum ofGPUs
Setup
Requirements
Node.js
20.11+npm
10+
Install
npm installBuild
npm run buildTest
npm run testOptional live test against the public endpoint:
GRACC_LIVE_TESTS=1 npm run test:liveRun Via STDIO
For local MCP clients that spawn the server as a subprocess:
npm run dev:stdioOr after building:
npm run start:stdioRun Via HTTP
Optional stateless Streamable HTTP endpoint:
npm run dev:httpOr after building:
npm run start:httpDefault 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:latestThe 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:
latestandmainon the default branch1.2.3and1.2when av1.2.3git tag is pushedsha-<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 Servicesk8s/overlays/dev: a standalonegracc-mcpnamespace using the published imagek8s/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-mcpon port3333for the native MCP endpointmcpoon port8000as 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/devThe deployment creates two cluster-internal services:
gracc-mcp:3333-> native MCP endpoint at/mcpgracc-mcp-openapi:8000-> OpenAPI bridge with docs at/docs
In-cluster URLs:
http://gracc-mcp:3333/mcphttp://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_URLGRACC_DEFAULT_INDEXGRACC_ALLOWED_INDICESGRACC_MAX_RANGE_DAYSGRACC_MAX_BUCKETSGRACC_MAX_TOP_NGRACC_MAX_SAFE_QUERY_SIZEGRACC_MAX_RESULT_BYTESGRACC_TIMEOUT_MSGRACC_RETRY_COUNTGRACC_HTTP_HOSTGRACC_HTTP_PORT
Public deployment settings:
Variable | Default | Purpose |
|
| Register the expert |
|
| Express |
|
| HTTP requests per client IP per window. |
|
| Rate limit window. |
|
| Maximum simultaneous requests to GRACC per process. |
|
| Requests allowed to wait for a slot; beyond this the tool returns a "busy" error. |
|
| Largest GRACC response the server will read. |
|
| How long identical queries are served from memory. |
|
| 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
_searchis useddefault 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_querybuilds a fresh request from validated parts instead of forwarding the caller's JSONper-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-Afterlonger than 5 seconds is not waited outresult payload size cap for
run_safe_query
Known Assumptions And Field Caveats
Known assumptions
gracc.osg.summaryis the authoritative public alias used by this server.EndTimeis the default time field because it is used in the public GRACC direct-query examples.CoreHoursis 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
@timestampis available from the public mappings but appears to be ingest-oriented, not job-end-oriented.processor_count_sumis a sum ofProcessorsacross matching summary documents, not a distinct hardware inventory count.CommonNamemay 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-
graccindices with different field types; this server avoids them.
Open questions
Is
CommonNamethe best default "submitter" dimension for every downstream use? Checking GRACC dashboards or asking site stakeholders would settle it.Should dimensions like
PayloadSiteNameorExecutePooljoin the allowlist? Current public dashboards and usage examples would show whether they are needed.If public docs standardize other summary aliases, update
GRACC_ALLOWED_INDICESand 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.tomlexamples/claude-desktop-config.jsonexamples/prompts.mdk8s/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/mcpOver STDIO, after npm run build:
claude mcp add gracc -- node /absolute/path/to/gracc-mcp/dist/index.jsChatGPT Or Other MCP-Compatible Clients
Use either:
STDIO mode pointing to
dist/index.jsStreamable 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only MCP for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
A paid remote MCP for AI SDK data query MCP, built to return verdicts, receipts, usage logs, and aud
Query, browse, and automate OmegaAI workspaces from any MCP client. Streamable HTTP with OAuth 2.0.
Read-only AI/LLM cost tools with current MCP discovery and attributable Registry transport.
Related MCP Servers
- AlicenseAqualityDmaintenanceRead-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.12MIT
- AlicenseAqualityDmaintenanceMCP server for querying OpenAI usage and cost data, including spend summaries, daily breakdowns, month-over-month comparisons, and token usage by model.3MIT
- AlicenseNot gradedqualityDmaintenanceA 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
- FlicenseBqualityDmaintenanceA secure, read-only MCP server that enables AI assistants to inspect transactions, vendor performance, wallet balances, and analytics through validated REST API calls.19-