Model Context Protocol (MCP)

MCP is the open protocol AI assistants use to talk to external tools. This server is auto-built from the Grants data models - one install line, configure your AI host, and your assistant can list, read, create, update, and delete data on your behalf. Auth uses the same personal access tokens the rest of the API accepts, so you control exactly which models the assistant can touch.

Install

One line, one file. The script lands under your home directory - no pip install, no system-wide changes. Pick your OS in the tabs below.

curl -fsSL https://granttool.de/xapi2/mcp/install.sh | bash

Provide a token

Create a personal access token (PAT) from the Integrations menu and tick the scopes the AI should have - read-only for safe exploration, or read + write for hands-on editing. PATs are revocable and scoped, so a leaked token can't outlive a single revocation. Pass the token via the GRANTSMCP_TOKEN environment variable in your AI host's server config (recommended), or run grantsmcp login --token pat_... once and the token persists for every future invocation.

export GRANTSMCP_TOKEN=pat_...
grantsmcp doctor

Configure your AI client

Every MCP-capable AI host accepts a small JSON config that tells it which servers to launch. Drop the snippet below into the host's MCP config file and restart it. The server runs locally as a subprocess of the host - it never accepts inbound connections from the network.

{
  "mcpServers": {
    "grantsmcp": {
      "command": "grantsmcp",
      "args": [],
      "env": {
        "GRANTSMCP_TOKEN": "pat_..."
      }
    }
  }
}

What the assistant can do

Each data model exposes one tool per available operation. Read tools ({type}_list, {type}_get) are safe to call freely; write tools ({type}_create, {type}_update, {type}_delete) mutate data and should be confirmed with the user. The server cannot create users, manage tokens, or change billing - those happen in the Grants web UI.

Example prompts

Once the server is registered in your AI client, the model picks up the tool list automatically. These prompts show how to work with the data models together with the AI.

Confirm you can talk to the Grants server, then list the
five most recently created derived_docs. Summarise the result.

Environment variables

Local diagnostics

The same script is runnable directly from a shell - useful when the AI client reports that the server failed to start.

# Server reachable? Token valid? Tool surface rendered?
grantsmcp doctor

Security

The server runs locally as a subprocess of your AI client and never accepts inbound connections from the network. Tool calls only target the official API URL baked into your script; a cross-origin redirect would have its Authorization header stripped before the next hop. Revoke the token any time from the Integrations menu.

• No user or token management. The server cannot create accounts, change passwords, mint or revoke tokens, or touch billing - only data models.
• PAT scopes are the brake. Grant exactly the scopes the assistant needs. A read-only PAT turns the server into a safe exploration session.
• Write tools are marked destructive. Most AI clients prompt before calling - leave the confirmation switch on.
• Server checks still run. Validation, access rules, and audit logging fire on every tool call exactly as they do for the web UI.

Telemetry + auto-update

The server sends one anonymous analytics event per tool call (tool name, version, OS - no arguments, no field values) so the team running this app can see how it's used. Disable with GRANTSMCP_NO_TELEMETRY=1. Separately, the server checks for a newer version at most once every 24 hours and replaces itself in place; GRANTSMCP_NO_AUTOUPDATE=1 disables that. Updated bytes activate on the next host restart - the running session keeps the old code so an in-flight request can't break.