MCP Server

Why

An agent working in a Grit project has to answer the same questions over and over. What is the URL for listing users? Does that endpoint need an admin token? What fields does Invoice actually have? Without a way to ask, it greps, infers, and gets it subtly wrong — usually by dropping the /api/v1 prefix or inventing a field that isn't there.

The MCP server answers those three questions from your source files, so the agent reads facts instead of guessing.

Setup

With Claude Code, one command:

claude mcp add grit -- grit mcp serve --project /path/to/your-project

For any other MCP client, add it to the client's config:

{
  "mcpServers": {
    "grit": {
      "command": "grit",
      "args": ["mcp", "serve", "--project", "/path/to/your-project"]
    }
  }
}

Omit --project and the server searches upward from its working directory for grit.json, the same way every other Grit command finds your project.

The tools

grit_project_info

Architecture, frontend framework, Go module path, the CLI version that scaffolded the project, and which apps exist. Worth calling first — it tells the agent whether Go code lives at the root or under apps/api, which is the thing most often assumed wrongly.

grit_list_routes

Every registered route with its method, full path including the /api/v1 prefix, handler, and access level (public, protected, admin). Takes optional method and contains filters so the agent can ask a narrow question instead of pulling 140 routes into its context.

grit_describe_models

Every GORM model with its fields, Go types, JSON names, and GORM tags — the exact shape of a request or response body, and the column constraints behind it. Pass model to fetch just one.

Read-only, and static on purpose

Every tool answers by parsing your source. None of them connects to a running server or a database, and none of them writes anything. That is a design decision, not a first-draft limitation, and it buys four things:

• It works on a checkout that has never been started — no docker compose up first.
• It needs no credentials, so there is no secret to leak into an agent's context.
• It cannot mutate your repo.
• It cannot be talked into running a migration by instructions hidden in a README or an issue comment.

An agent that wants to change your project still has to call the CLI, where the change lands in your diff and you review it like any other.

Scope

The server targets Grit's web and API architectures — single, double, triple, api, and mobile. Standalone desktop projects created with grit new-desktop have a different shape (Wails bindings rather than HTTP routes) and are not covered yet.

Two further tools are planned but deliberately not shipped yet: openapi and recent_errors. Both need a running server and a database connection, which means a credential and connection story the read-only tools above do not require — a meaningfully different surface, worth doing separately rather than bolting on.