Developer recipe

Connect an AI agent through MCP

Give Claude Desktop, Cursor, or another MCP client controlled access to your GramClaw workspace.

Result
The AI client can discover GramClaw tools and act on the Telegram accounts permitted by the API key.
Time
10 minutes
Key scopes
readwritesend

Choose the minimum access

Create a dedicated API key in Settings. Select read for search and reporting, write for pipeline changes, and send only when the agent should be able to send messages or campaigns.

  • MCP tool calls execute directly. The API key is the authorization, so GramClaw does not add the dashboard AI confirmation screen to remote MCP actions.

Option A: Connect the remote MCP URL

Use this format when your MCP client accepts a remote Streamable HTTP server. Treat the full URL like a password because it contains the key.

Remote MCP URL
https://gramclaw.com/api/mcp?key=gc_live_replace_with_your_key

Option B: Configure Claude Desktop locally

Add the server to claude_desktop_config.json, then restart Claude Desktop. This keeps the key in the MCP process environment rather than the connector URL.

claude_desktop_config.json
{
  "mcpServers": {
    "gramclaw": {
      "command": "npx",
      "args": ["-y", "gramclaw-mcp"],
      "env": {
        "GRAMCLAW_API_KEY": "gc_live_replace_with_your_key",
        "GRAMCLAW_BASE_URL": "https://gramclaw.com"
      }
    }
  }
}

Verify without sending

Start with a read-only request so you can verify the workspace and connected accounts before granting or using send access.

Prompt
Use gramclaw_whoami to verify the connection. Then list my five newest chats. Do not send or change anything.
  • An invalid-key error means the key is malformed, revoked, or was copied incorrectly.
  • A subscription-required error means the key owner's trial or subscription is inactive.
  • A missing-scope error names the scope required by the requested tool.
  • Revoke the dedicated key immediately from Settings if its URL or configuration is exposed.
Chat on Telegram