Grantd MCP server
✓ VerifiedLets AI agents securely act on a user's behalf across third-party APIs by brokering OAuth tokens through a secure, encrypted vault.
Also known as rafavecchi/grantd, grantd-mcp
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Jun 9, 2026
- License
- MIT
What is Grantd MCP?
Grantd lets AI agents securely act on a user's behalf across third-party APIs by brokering OAuth tokens through a secure, encrypted vault.
Summary generated from the project's README
About Grantd MCP server
Grantd acts as a secure OAuth token broker designed for AI agents that need to interact with third-party services like Gmail, GitHub, Slack, and Notion. Instead of passing sensitive credentials directly to a large language model, this server vaults tokens on the backend using AES-256-GCM envelope encryption. This architecture ensures that raw access tokens never reach the LLM or the caller, as the proxy injects them at the network boundary before returning only the provider response.
Developers can deploy this as self-hosted infrastructure using a TypeScript and Postgres stack. To use it with an MCP client like Claude Desktop or Cursor, you must run a broker instance and provide a base URL and an API key via environment variables. The server exposes specific tools including list_providers, check_connection, create_connect_link, and call_provider. If an agent attempts to use a service without permission, the system returns an authorization_required status along with a link for the user to connect their account.
What you can do with it
- 1Manage third-party service permissionsAn AI agent can identify which external services are available for connection through the broker.
- 2Handle missing user authorizationsThe system can prompt a user to authenticate when an agent tries to access a disconnected account.
- 3Execute secure API requestsAn agent can perform actions on behalf of a user by calling a provider tool without ever seeing the underlying token.
Written from the project's README. Every use case is checked against a quote from it.
How to install Grantd MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Grantd MCP in Claude Code
$ claude mcp add --env 'GRANTD_API_KEY=<YOUR_GRANTD_API_KEY>' grantd -- npx -y grantd-mcpInstall Grantd MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"grantd": {
"command": "npx",
"args": [
"-y",
"grantd-mcp"
],
"env": {
"GRANTD_API_KEY": "<YOUR_GRANTD_API_KEY>"
}
}
}
}Install Grantd MCP in VS Code
.vscode/mcp.json
{
"servers": {
"grantd": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"grantd-mcp"
],
"env": {
"GRANTD_API_KEY": "<YOUR_GRANTD_API_KEY>"
}
}
}
}Install Grantd MCP in VS Code CLI
$ code --add-mcp '{"name":"grantd","type":"stdio","command":"npx","args":["-y","grantd-mcp"],"env":{"GRANTD_API_KEY":"<YOUR_GRANTD_API_KEY>"}}'Install Grantd MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"grantd": {
"command": "npx",
"args": [
"-y",
"grantd-mcp"
],
"env": {
"GRANTD_API_KEY": "<YOUR_GRANTD_API_KEY>"
}
}
}
}Install Grantd MCP in Codex
$ codex mcp add grantd --env 'GRANTD_API_KEY=<YOUR_GRANTD_API_KEY>' -- npx -y grantd-mcpInstall Grantd MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.grantd] command = "npx" args = ["-y", "grantd-mcp"] [mcp_servers.grantd.env] GRANTD_API_KEY = "<YOUR_GRANTD_API_KEY>"
Install Grantd MCP in Gemini CLI
$ gemini mcp add -s user -e 'GRANTD_API_KEY=<YOUR_GRANTD_API_KEY>' grantd npx -- -y grantd-mcpInstall Grantd MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"grantd": {
"command": "npx",
"args": [
"-y",
"grantd-mcp"
],
"env": {
"GRANTD_API_KEY": "<YOUR_GRANTD_API_KEY>"
}
}
}
}Configuration
GRANTD_API_KEYRequiredSecretA Grantd secret key (sk_...). Treat it like a password.
GRANTD_BASE_URLBase URL of your Grantd broker (default http://localhost:8787).
GRANTD_END_USERDefault end-user id so tools don't need it passed each call.
| Name | Description | |
|---|---|---|
| GRANTD_API_KEY | A Grantd secret key (sk_...). Treat it like a password. | RequiredSecret |
| GRANTD_BASE_URL | Base URL of your Grantd broker (default http://localhost:8787). | |
| GRANTD_END_USER | Default end-user id so tools don't need it passed each call. |
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablerafavecchi/grantd is public and reachablegithub.com/rafavecchi/grantd ↗Pass
- Package names this repository as its sourcegrantd-mcp names rafavecchi/grantd as sourcenpmjs.com/package/grantd-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-06-09github.com/rafavecchi/grantd ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from grantd-mcpPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubGrantd
OAuth-for-agents: a dead-simple, MCP-native OAuth token broker that lets AI agents securely act on a user's behalf across third-party APIs (Gmail, Slack, GitHub, Notion…). Tokens are vaulted server-side and never touch the LLM.
Stack: TypeScript · Hono · Postgres · generic OAuth2 driven by a declarative provider registry · envelope encryption (AES-256-GCM, key-versioned) · Postgres advisory locks for refresh concurrency (no Redis). Security model and how to report issues: SECURITY.md.
Security at a glance
Grantd vaults users' OAuth tokens, so security is the product, not a feature. The fundamentals:
- Tokens encrypted at rest — AES-256-GCM envelope encryption, fresh IV per record, key-versioned, and fail-closed (a missing key refuses to write; it never silently stores plaintext).
- Tokens never reach the LLM or the caller. The proxy injects the access token at the network boundary and returns only the provider's response — the raw token is never serialized back.
- API keys hashed at rest (pbkdf2-sha256, peppered); the raw
sk_key is shown once. - No SQL injection — every query is a parameterized
postgres.jstagged template. - Tenant isolation on every query by environment id; Row-Level Security enabled on all tables so a Postgres REST layer (e.g. Supabase/PostgREST) can't read the vault.
- 256-bit random OAuth
state+ session tokens; PKCE (S256) where the provider supports it. - Durable, Postgres-backed rate limiting — per secret key on auth routes, per IP on public routes.
This is open-source infrastructure you run yourself. Self-hosting responsibilities (key custody, TLS, an edge/WAF for volumetric DoS) and known limitations are documented honestly in SECURITY.md. If you intend to run a hosted, multi-tenant deployment that holds other people's tokens, work through HOSTED-CHECKLIST.md first.
Providers
| Provider | Status |
|---|---|
| Google (Gmail, Calendar, …) | ✅ Verified end-to-end, including token refresh |
| GitHub | ✅ Verified end-to-end |
| Slack | 🧪 Experimental — config present, not yet verified against live OAuth |
| Notion | 🧪 Experimental — config present, not yet verified against live OAuth |
Adding a provider is data, not code (see src/providers.ts). Help verifying Slack/Notion is welcome.
Quick start (dev)
npm install
npm run keygen # prints an ENCRYPTION_KEYRING + API_KEY_SALT
cp .env.example .env # then paste keygen output + your DATABASE_URL
npm run migrate # apply SQL migrations
npm run dev # start the broker on :8787
MCP server
Exposes the broker to an AI agent (Claude Code / Cursor / Claude Desktop) as tools:
list_providers, check_connection, create_connect_link, and call_provider. The
auth-gating wedge: if the agent calls call_provider for a user who isn't connected, it
returns an authorization_required result with a connect link instead of failing.
The MCP server is published to npm as grantd-mcp, so
you don't need to clone this repo to use it — just point an MCP client at it (you do need a running
broker and a secret key). For local development: npm run mcp (needs the broker running); smoke
test: npm run mcp:test.
Add to Claude Code:
claude mcp add grantd \
--env GRANTD_API_KEY=sk_... \
--env GRANTD_BASE_URL=https://your-broker.example.com \
--env GRANTD_END_USER=user-123 \
-- npx -y grantd-mcp
Or in a Cursor / Claude Desktop mcpServers config:
{
"mcpServers": {
"grantd": {
"command": "npx",
"args": ["-y", "grantd-mcp"],
"env": {
"GRANTD_API_KEY": "sk_...",
"GRANTD_BASE_URL": "https://your-broker.example.com",
"GRANTD_END_USER": "user-123"
}
}
}
}
Layout
migrations/ SQL schema (Supabase/Postgres compatible)
scripts/ keygen + migrate helpers
src/
config.ts env loading + validation + keyring parse
crypto.ts envelope encryption + API-key hashing
db.ts postgres.js client
providers.ts declarative provider registry (Google, GitHub, Slack, Notion)
oauth.ts generic OAuth2 client (authorize / exchange / refresh) driven by the registry
server.ts Hono app + routes (WIP)
Grantd MCP questions
How do I add Grantd MCP to Claude Code?
Run claude mcp add --env 'GRANTD_API_KEY=<YOUR_GRANTD_API_KEY>' grantd -- npx -y grantd-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Grantd MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does the MCP server handle unauthorized requests?
If an agent attempts to call a provider for a user who is not connected, the server returns an authorization_required result along with a connection link.