Skip to main content

MCP Token Management

MCP tokens authenticate AI coding agents (Claude Code, Cursor, VS Code, Windsurf, Codex, Antigravity) to your Appgrammar account. Tokens are bearer tokens sent with every MCP request.

Generating a Token​

In the web UI, go to MCP & Hooks in the sidebar. Enter a descriptive name for the token (e.g., "Claude Code - work laptop") and click Generate.

caution

The token value is shown only once. Copy it immediately and store it securely. You cannot retrieve it later.

Via the API:

POST /api/mcp/tokens
{
  "name": "Claude Code - work laptop"
}

Returns the token value and metadata.

Configuring Your Agent​

The MCP & Hooks page provides ready-to-use configuration snippets for all 6 supported IDEs/CLIs. Select your tool, and the snippet updates with your real token and team scope.

Claude Code​

Run in your terminal:

claude mcp add --transport http appgrammar https://appgrammar.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Cursor​

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "appgrammar": {
      "url": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

VS Code​

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "appgrammar": {
      "type": "http",
      "url": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Windsurf​

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "appgrammar": {
      "serverUrl": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Codex​

Add to ~/.codex/config.toml:

[mcp_servers.appgrammar]
url = "https://appgrammar.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_TOKEN" }

Antigravity​

Add to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "appgrammar": {
      "serverUrl": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Team-Scoped Connections​

If you belong to a team, you can create an MCP connection that automatically applies your team's conventions to every appgrammar created through it. Add the X-Team-Id header with your team's UUID.

Why Use Team Connections?​

Without a team connection, you must pass team_id on every tool call to associate appgrammars with a team. With a team connection, the server reads the team from the X-Team-Id header automatically:

  • Appgrammars created via appgrammar_create belong to the team
  • Forks via appgrammar_fork belong to the team
  • All tool operations inherit the team context
  • Team conventions are injected into execution prompts

Configuration Examples​

You can run both a personal and a team connection simultaneously. The team connection uses a different server name (e.g., appgrammar-acme) so they don't conflict.

Claude Code​

# Personal connection (no team)
claude mcp add --transport http appgrammar https://appgrammar.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Team connection
claude mcp add --transport http appgrammar-acme https://appgrammar.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "X-Team-Id: YOUR_TEAM_UUID"

Cursor​

{
  "mcpServers": {
    "appgrammar-acme": {
      "url": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-Team-Id": "YOUR_TEAM_UUID"
      }
    }
  }
}

VS Code​

{
  "servers": {
    "appgrammar-acme": {
      "type": "http",
      "url": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-Team-Id": "YOUR_TEAM_UUID"
      }
    }
  }
}

Windsurf​

{
  "mcpServers": {
    "appgrammar-acme": {
      "serverUrl": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-Team-Id": "YOUR_TEAM_UUID"
      }
    }
  }
}

Codex​

[mcp_servers.appgrammar-acme]
url = "https://appgrammar.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_TOKEN", "X-Team-Id" = "YOUR_TEAM_UUID" }

Antigravity​

{
  "mcpServers": {
    "appgrammar-acme": {
      "serverUrl": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-Team-Id": "YOUR_TEAM_UUID"
      }
    }
  }
}

Finding Your Team UUID​

Your team UUID is visible on the MCP & Hooks page when you select a team in the team scope selector. The configuration snippets update automatically with the correct UUID.

You can also find it via the API:

GET /api/teams

Validation​

The server validates the X-Team-Id header on every request:

  • The value must be a valid UUID
  • You must be an accepted member of the team

If validation fails, the server returns 403 Forbidden with a descriptive error message.

info

The same MCP token works for both personal and team connections. Team context is determined by the X-Team-Id header, not the token.

Auto-Sync Hooks (Claude Code)​

The MCP & Hooks page includes an Auto-Sync Hooks section for Claude Code users. This generates a .claude/hooks.json template that gives the agent soft reminders to run appgrammar_update after file changes.

For other IDEs/CLIs, the agent uses the appgrammar.md file in the project root to know when to sync. See Keeping the Blueprint in Sync for details.

API Reference​

Get MCP Configuration​

GET /api/mcp/config

Returns the MCP server URL and connection details for your account.

List Active Tokens​

GET /api/mcp/tokens

Lists all your active tokens with names, creation dates, and last-used timestamps. Token values are not returned -- only metadata.

Revoke a Token​

DELETE /api/mcp/tokens/:tokenId

Immediately invalidates the token. Any agent using it will receive authentication errors on the next request. Revocation is instant and irreversible.

In the web UI, each token in the list has a Revoke button.