Documentation

Try Grounded.Codes in 30 seconds

Connect your coding agent to Grounded.Codes over MCP and start getting source-backed syntax guidance, architecture answers, and product comparisons.

Prerequisites

1Sign up for free to create your account.
2Generate an API key from your dashboard.
3Add the MCP server configuration to your agent and send syntax, architecture, or comparison requests directly.
!Beta note: Currently supports Python and TypeScript ecosystems only. Data freshness may vary — sources are refreshed periodically.

Agent configuration

Select your coding agent and paste the configuration into your local MCP settings.

Terminal

claude mcp add grounded --transport http https://mcp.grounded.codes/mcp --header "Authorization: Bearer YOUR_API_KEY"

Or add manually to config file

claude-code-config

// .mcp.json
{
  "mcpServers": {
    "grounded": {
      "type": "url",
      "url": "https://mcp.grounded.codes/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your key from the dashboard.

What your agent gets back

Grounded.Codes responses are optimized for LLM consumption and include trust metadata.

response.json

{
  "winner": "uv",
  "matrix": [
    {
      "candidate": "uv",
      "summary": "Higher health score and stronger current momentum.",
      "source_urls": ["https://docs.astral.sh/uv/"]
    }
  ],
  "sources": [
    { "title": "uv docs", "url": "https://docs.astral.sh/uv/" }
  ],
  "confidence": 0.81,
  "retrieval_mode": "stored"
}

For deeper coverage, Grounded will use stored evidence first and only fall back to bounded live research when the stored sources are too thin.

Tool reference

The three public MCP tools available through the Grounded.Codes knowledge API.

Tool	Description
`get_syntax_guidance`	Get grounded Python and TypeScript syntax help with snippets, gotchas, and explicit sources.
`get_architecture_guidance`	Ask architecture questions and get source-backed recommendations, tradeoffs, and implementation recipes.
`compare_developer_products`	Compare packages, platforms, and dev tools with an explicit winner, comparison matrix, and citations.

Troubleshooting

Common issues when connecting your agent to Grounded.Codes.

Getting 401 Unauthorized?

Check that your API key is valid, has not been revoked, and includes the gk_ prefix. The Authorization header must be formatted as: Bearer gk_your_key_here.

Getting 429 Too Many Requests?

You have exceeded the per-minute rate limit. Wait a moment and retry. Free-tier keys are limited to 60 requests per minute.

Connection refused or timeout?

Verify that the MCP URL is exactly https://mcp.grounded.codes/mcp and that your network allows outbound HTTPS connections.

Empty or missing responses?

The ecosystem parameter must be either python or typescript. Other values are not supported during beta.