Plugins

MCP

An MCP server for your app, so an agent works through the same rules a person does.

Not the same thing as the MCP server under AI Workflows. That one runs on your machine while you build, and answers questions about your code: which routes exist, what fields a model has, which files you have edited. This one runs inside your deployed app and exposes its data, to an agent acting as one of your users. One helps you write the app; the other lets somebody use it.

The decision the rest follows from

A tool call does not touch the database. It builds an HTTP request and runs it in process against the same gin engine that serves the browser.

That is not a shortcut taken for want of a cheaper path. A Grit API decides what a caller may do in middleware and in services: authentication, the organization scope, the role, the per-resource policy, the module switch, the record-level scope, the validation tags, the audit log. A tool that queried GORM directly would bypass every one of them, and would have to reimplement them. Two implementations that start identical and drift, and the one that drifts is the one nobody is looking at.

Running through the router costs a function call and some JSON. What it buys is that an agent is structurally incapable of doing something the same person could not do in the browser, and that every tool call lands in the audit log the same way a click does.

One connection is one key

A person makes a connection in the app: a name, and the tools it may use. That mints a secret API key that acts as them, and the key is narrowed twice, both times from the tools rather than by choice:

  • Scopes, to the permissions those tools declare, so the key cannot reach a permission no chosen tool needs.
  • Endpoints, to the routes those tools call. This is the one that makes a read-only connection structurally read-only: it holds no POST route, so a write is refused by the API key middleware before any handler runs, whatever the agent asks for.

Derived and not chosen, so nobody widens a connection by accident, and adding a tool to a resource later does not quietly widen the connections that already exist. A tool whose own role does not grant its permission is refused when the connection is made, because an agent must not be able to do more than the person who set it up.

Revoking the connection revokes the key, in that order and immediately. The alternative, one MCP_API_KEY for the whole app, cannot say who did what, cannot be narrowed to the twelve tools one person needs, and cannot be revoked without breaking everybody.

Using it, step by step

Install it

grit plugin add mcp

Writes internal/mcp (the transport, the tool registry, the in-process caller), the connection model and service, and mounts POST /mcp at the root.

Run the migration

grit migrate

Two tables: the connections, and what every agent did with them.

Make a connection

POST /api/v1/mcp-connections

A name and the tools it may call. It answers with a key, once. Any signed-in person can make their own: it acts as them and can do no more than they can.

Point a client at it

The mcpServers entry below. The key goes in the Authorization header.

Pointing a client at it

.mcp.json
{
"mcpServers": {
"my-app": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": {
"Authorization": "Bearer grit_sk_..."
}
}
}
}

Streamable HTTP, and deliberately the plain half of it: every JSON-RPC request gets a JSON answer rather than an event stream. The transport allows that, and no tool reports progress, so a stream would be a second code path with nothing to carry. A GET on the endpoint, which is how a client opens the stream half, answers 405 with Allow: POST rather than leaving it waiting.

Stateless: every request carries its own key, so there is no session to create, lose or pin to one process. It can sit behind a load balancer and scale to zero.

It implements initialize (protocol 2025-11-25 down to 2024-11-05), ping, tools/list and tools/call, and it handles batches. A version it has never heard of gets the oldest it speaks rather than a refusal, because a client from the future can still talk over 2024-11-05 and a refusal looks to the person like the server being down.

Writing a tool

The generated CRUD tools are the base, not the ceiling: the interesting tools in any app are the ones that are not create-read-update-delete. Yours go in internal/mcp/custom_tools.go, which Grit never rewrites.

internal/mcp/custom_tools.go
func init() {
Register(Tool{
Name: "send_invoice",
Title: "Send an invoice",
Description: "Emails an invoice to its client and marks it sent. " +
"The invoice must be a draft. Takes the invoice number or its id.",
Group: "Invoices",
Permission: "invoices.edit",
Write: true,
Routes: []string{
"GET /api/v1/invoices",
"POST /api/v1/invoices/:id/send",
},
Schema: map[string]any{
"type": "object",
"properties": map[string]any{
"invoice": map[string]any{
"type": "string",
"description": "The invoice number, or its id.",
},
},
"required": []string{"invoice"},
},
Exec: func(ctx context.Context, call *Call, args map[string]any) (any, error) {
term, err := String(args, "invoice")
if err != nil {
return nil, err
}
id, err := Resolve(ctx, call, "invoice", "/api/v1/invoices", term)
if err != nil {
return nil, err
}
result, err := call.Post(ctx, "/api/v1/invoices/"+id+"/send", nil)
if err != nil {
return nil, err
}
if !result.OK() {
return nil, fmt.Errorf("%s", result.Message())
}
return map[string]any{"sent": true, "invoice_id": id}, nil
},
})
}

Four things in there are load-bearing. Routes is a security boundary and not documentation: the connection's key is restricted to the union of its tools' routes, so a route left out is refused at runtime by the app itself. Permission is what keeps the tool off the list for somebody whose role lacks it. Write and Destructive drive the hints a client uses to decide whether to confirm with the person first. And Exec goes through call.Post rather than GORM, for the reason at the top of this page.

Arguments, as a model actually sends them

The schema says a field is a number and the model sends "5", because that is what the person typed. It says the field is an id and the model sends the customer's name. Refusing both is correct by the schema and useless in practice: the call fails, the model apologises, and the person is no further forward.

So the helpers are forgiving about shape and strict about meaning. Int reads "7", Float reads "$1,250.50", Strings reads a bare item as a list of one. Resolve turns a name into an id by asking the app, so the lookup is scoped to what this connection may see.

What they never do is guess which record was meant. A name matching more than one returns an error naming the candidates, which the model can put back to the person. Picking the first match is the behaviour that quietly invoices the wrong customer.

Paging is capped at 100 whatever the model asks for. “List every invoice” with no page size is a model requesting a hundred thousand rows it will then put in its own context.

What an agent did

Every call is recorded: the connection, the person, the tool, the arguments, whether it worked, the error if not, and how long it took. Refusals as well as successes, which are often the more interesting half.

GET /api/v1/mcp-connections your own connections
POST /api/v1/mcp-connections make one; answers with the key, once
GET /api/v1/mcp-connections/tools the tools your role lets you choose
DELETE /api/v1/mcp-connections/:id revoke it, and its key
GET /api/v1/mcp-connections/:id/calls what that agent did

call_count counts tool calls and nothing else: the handshake and every tools/list are excluded, because otherwise an idle client looks busy. last_used_at is every request, since “when did this agent last connect” is the question that one answers.

Tools for every resource, generated

grit generate resource Invoice writes internal/mcp/tools_invoices.go: list_invoices, get_invoice, create_invoice, update_invoice and delete_invoice, with schemas built from the field types. The permission on each comes from the route table the generator already writes, so the key allowlist and the role checks line up with no extra work.

The file registers itself from an init(), which is why there is no marker to inject at and why grit remove resource is a delete. Nothing imports it.

What the schemas do with each type: a select becomes an enum of its options, money is a number in ordinary units because a model asked for forty dollars sends 40, a date gets a format, and a belongs_to takes the related record's id or its name, resolved through the app. Required on create, optional on update, from one shared body builder so the two cannot drift.

Four kinds of field are never offered, each for its own reason: encrypted and sensitive columns, because a recovery phrase is not an agent's to set and a sensitive one cannot be read back to check; ServerSet, because a hook overwrites whatever is sent; files, because an upload is a multipart request this transport does not make; and a slug, because it is derived from its source and setting it directly puts the two out of step.

A relation's lookup route is declared alongside the write route, which is easy to miss and not optional: resolving a client by name is a GET /api/v1/clients, and a route a tool does not declare is one its own key refuses.

What is not in this release

The connection screens in the admin, and grit mcp sync for regenerating schemas after a field changes (grit generate resource --force does it today). Until the screens land, a connection is made over the API, which is also how a headless project would do it.

Related plugins

Near neighbours, and what each one is for instead.

Everything else is on the marketplace, and four ways to extend says when a plugin is the wrong tool for the job.