Connect an agent with MCP

Connect an agent to Gridstate’s hosted Model Context Protocol (MCP) server, verify the connection, and run a source-backed grid-data query.

Hosted endpoint

Gridstate serves MCP over HTTP at https://mcp.gridstatelabs.com/mcp. The same authentication, release, rate limit, and audit controls protect the REST API and MCP server.

Create a scoped key

Create a key in the Gridstate console. Choose data access for public records or assessment access for site-screening tools.

The console displays the secret once. Copy it before leaving the page.

Export the credential

Keep the key in the environment that starts your agent client:

export GRIDSTATE_API_KEY="your_gridstate_api_key_here"

Configure your client

Choose your client and add the hosted server:

claude mcp add --scope user --transport http gridstate \
  https://mcp.gridstatelabs.com/mcp \
  --header "Authorization: Bearer ${GRIDSTATE_API_KEY}"

Protect local MCP configuration

Credential-bearing MCP files must stay out of version control. Gridstate accepts tokens only through the Authorization header.

Verify the connection

Confirm that your command-line client saved the server:

claude mcp get gridstate

Restart graphical clients after changing their MCP configuration.

Run an evidence query

Ask the connected agent:

Use Gridstate to find up to 10 queue projects over 100 MW in Texas. Check coverage first, cite each source locator, and state every data limitation.

A working connection calls check_data_coverage before search_projects. The answer should cite source locators and retain the limitations returned by each tool.

An empty result means no acquired evidence matched the query. It does not prove that no project exists.

Choose the correct tool

Every tool is read-only, idempotent, and bounded to 25 records. Tool responses include text and structured JSON.

Tool	Use it for	Boundary
`search_projects`	Queue and reported transmission projects	No claim about available capacity, cost, or schedule
`get_queue_record_context`	Normalized detail and the preserved source row	Verifies extraction, not the publisher’s fact
`search_generation`	EIA plant and generator inventory	Preliminary inventory may be revised
`search_operations`	Generator-month and balancing-authority-hour history	Historical conditions are not forecasts
`check_data_coverage`	Coverage, quality counts, provenance, and allowed claims	Internal consistency is not independent validation
`search_evidence`	Extracted prose, tables, and figures	Retrieval still requires interpretation
`assess_site_readiness`	A coordinate-resolved large-load screen	No capacity, eligibility, cost, schedule, or siting claim
`compare_site_readiness`	Two to ten sites under one evidence contract	Never ranks by record density or inferred capacity
`monitor_grid_changes`	Bounded before-and-after canonical changes	Zero events do not prove nothing changed outside Gridstate

Understand scope-aware discovery

The server shows only tools allowed by the key:

Credential scope	Discovered tools
`commercial-core:read`	Released commercial data tools
Site-screening scopes	Commercial tools plus site assessment and comparison
`data:read`	Acquired evidence search and change monitoring

Resolve connection errors

Use the returned status to choose the next action:

Result	Action
`401`	Replace the missing, revoked, or malformed key
`403`	Create a key with the scope required by the tool
`429`	Wait for the returned retry interval
No tools	Restart the client after updating its configuration
Empty results	Call `check_data_coverage` before broadening the claim

Local development uses http://127.0.0.1:4040/mcp.

Connect an agent with MCP

On this page