An MCP plugin: an MCP server for the app, with tools generated for every resource

Open
#224 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
18/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
go
Domain
api, backend

Research direction

Start by reading the resource generator and route generation described in the issue, then inspect the existing API key service and endpoint allowlists it references. The proposal spans a new MCP transport, authentication, tool registry, generated CRUD tools, admin screens, migrations, tests, documentation, and generator removal behavior. Done means the plugin and resource lifecycle work end to end, including permission checks and a compiling project after removal.

Written by the indexing model from the issue text.

Description

enhancement

What I want

A first-party MCP plugin. grit plugin add mcp gives the project an MCP server, and from then on every resource generated with grit generate resource gets its MCP tools automatically: list, get, create, update and delete, with input schemas built from its fields. grit remove resource takes them away again.

Today every Grit project that wants Claude, Cursor or any agent to work in it writes the server, the auth and every tool by hand. I have now done this twice:

This is the expanded form of the "MCP from resources" proposal in #179.

What I set up by hand in Outpost (the reference design)

  1. Transport. Streamable HTTP at POST /mcp, mounted on the Gin engine at the root (outside the /api groups, because it authenticates itself).
    • Every JSON-RPC request gets a JSON answer: the transport allows that in place of a stream, and no tool sends progress.
    • It handles batches. Notifications get 202, and GET and DELETE answer 405 with Allow: POST.
    • It is stateless: every request carries its key, so there is no session to keep or lose.
    • It implements initialize (protocol 2025-11-25 down to 2024-11-05), ping, tools/list and tools/call.
    • initialize returns instructions that describe the workspace: its name, today's date, its currency, and that drafts are for a person to send.
  2. Auth: one connection is one key, never a shared secret. In the app's settings a person makes a connection: a name ("Claude Code") and the tools it may use.
    • That mints a Grit secret API key that acts as that person, in that workspace, limited (through the key's endpoint allowlist) to exactly the routes the chosen tools call.
    • A person can only choose tools their role allows. The plaintext key is shown once.
    • The key is read from Authorization: Bearer or X-API-Key. A bad or missing key gets 401 with WWW-Authenticate, and a message telling the person where to make one.
    • Revoking the connection revokes the key.
    • (Atlas used one shared ATLAS_API_KEY for everything, and had a bug where an empty key passed validation.)
  3. Every tool call goes through the API's own router. A tool does not touch GORM. Its Exec builds HTTP requests that run in process (httptest recorder) against the engine, with the connection's key and X-Organization-ID.
    • So authentication, tenancy, the role and policy checks, module switches, record scopes, validation and the audit log apply exactly as they do for the app, and are checked again on every call.
    • This was the decision that mattered most. A tool that queries the database directly is a second implementation of every rule, and it will drift.
  4. One tool registry for two consumers. Each tool is a Tool struct: name, title, description, group, the permission it needs, Write, the routes it calls, a JSON Schema for its parameters, and Exec.
    • The in-app assistant (chat) and MCP read the same catalogue, so a tool written once works in both.
  5. Arguments people actually send. Tools accept names as well as ids ("the client Kato Hardware"): a lookup resolves a name to one record, or answers with the candidates when it is ambiguous.
    • Money is in ordinary units, converted to minor units on the way in. Dates are YYYY-MM-DD in the workspace's time zone.
  6. Results.
    • Success: content (text JSON) plus structuredContent.
    • Refusals: the API's own message, with its field errors, as isError: true, so the model can correct itself rather than receive a protocol error.
    • Annotations: readOnlyHint comes from Write, and destructiveHint is false unless the tool deletes or voids.
  7. Every call is recorded: workspace, user, connection, tool, arguments, OK or not, status, error and duration. Each connection also keeps "last used" and a call count. The settings page shows the recent calls, so an owner can see what an agent did.
  8. Client setup shown in the app: a copyable mcpServers entry for Claude Code (type: "http", the /mcp URL, the Bearer header), plus Claude Desktop and Cursor.

What the plugin should do

grit plugin add mcp

  • Server: writes internal/mcp/ (the transport above, Tool, the registry, the in-process caller, argument helpers, name lookup) and mounts /mcp, with its body-size and WAF entries.
  • Connections: writes MCPConnection and MCPToolCall and registers them. Connections mint keys with the existing API key service and its endpoint allowlist.
  • Screens: adds connection management to the admin, and to the web app in a triple: create (choose tools by group, shown only if the role grants them), copy the key once, revoke, see recent calls.
  • Existing resources: generates tools for every resource already in the project (grit mcp sync).
  • Removal: grit plugin remove mcp reverses all of it.

On grit generate resource Invoice ... (with the plugin installed)

  • Tools: writes internal/mcp/tools_invoices.go and registers it at a // grit:mcp-tools marker:
    • list_invoices: search, filters for the filterable fields, sort, page and page size, returning the pagination meta;
    • get_invoice;
    • create_invoice, update_invoice and delete_invoice.
  • Permissions: each tool's Permission and Routes come from the routes the generator already writes, so the key allowlist and role checks line up with no extra work.
  • Input schema from the field types:
    • string and text become string, with maxLength when set;
    • int and float become number;
    • bool becomes boolean;
    • date and datetime become strings with a format;
    • enum becomes enum, with its values;
    • money is a number in ordinary units, described as such;
    • belongs_to[Client] accepts the related record's id or its label column, resolved with the name lookup;
    • many_to_many takes a list.
    • Required fields are required on create and optional on update.
  • Fields left out: encrypted columns, passwords, secrets, private files, and anything marked mcp:"-" are never in a schema or a result.
  • Ownership: --owned-by and --tenant-owned need nothing extra, because the call runs as the key's user through the router.
  • Descriptions: taken from the resource and field descriptions (or the YAML definition), so models know what each field means.
  • Flags:
    • --mcp=false skips a resource;
    • --mcp=read makes only list and get;
    • in YAML, mcp: { read_only: true, exclude: [field], tool_prefix: ... }.
  • Tests: a generated test that lists the tools, calls create, list, get, update and delete through /mcp with a minted key, and checks a key without the permission is refused.

Afterwards

  • grit remove resource Invoice removes the tools file and its registration, and drops the tools from existing connections. The pair is the contract: removal must leave a project that compiles.
  • grit sync (or grit mcp sync), after fields change, regenerates the schemas.
  • Custom tools: they live in files Grit never rewrites (internal/mcp/custom_*.go) and register through the same registry, for actions that are not CRUD (send an invoice, record a payment, move a deal). The generated CRUD tools are the base, never the ceiling.
  • grit doctor reports resources with no tools, and tools whose routes no longer exist.
  • Docs: a page covering the design rules above, so hand-written tools follow them too.

Why this is worth shipping

"Let my agent use my app" is the first thing people ask once an app exists, and the parts that are easy to get wrong are the same in every project:

  • auth per person, not one shared key;
  • calls that go through the same rules as the app;
  • schemas that match the fields;
  • removal that leaves a project that compiles.

Grit already has every piece: API keys with endpoint allowlists, policies, tenancy, the audit trail and the field-type metadata. The plugin is the glue between them, and the generator already knows everything the tools need.

Environment

grit 3.437.0 project, triple architecture, multitenant plugin. Go 1.27, Windows 11.

Dominant language
Go
Stars
152
Forks
20
Avg merge
1d 49m
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from MUKE-coder/grit

All issues in MUKE-coder/grit

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.