# Connect your AI agent to Statbrag

> Statbrag turns your stats into images ready to post. Your agent already has your data: it makes the cards and hands them to Buffer, which schedules posts on your social media. Setup takes about two minutes.

The page for people: https://statbrag.com/connect

## For an AI agent setting itself up

If the user sent you here to connect you, set yourself up:

1. Keep the user's agent token out of this chat: anything typed here can end up in logs and your context, and anyone with the token can make cards and send them to the user's Buffer as them. If they've already pasted it, tell them to revoke it and create a new one: https://statbrag.com/sign-in?next=%2Fapp%2Fagents
2. Find your own setup under "Set up your agent" below: Claude Code, Cursor, Hermes, Grok Bot. Follow its "For the agent" line: you add the server with a variable in place of the token, and the user sets that variable themselves, outside the chat. Grok Bot asks for the token with a secure secret card instead. If you already have a server called statbrag, ask the user before you replace it.
3. Tell the user what you did, exactly where to put their token, and whether they need to restart you. Once they have, call statbrag's `get_playbook` tool to check it works.

No token yet? Send the user to https://statbrag.com/sign-in?next=%2Fapp%2Fagents to sign in and create one under Agents. Claude.ai and ChatGPT can't add connectors by themselves: tell the user the steps for their app instead, and they sign in to Statbrag without a token.

## The quick way, for Claude Code, Cursor or Hermes

1. Sign in and create an agent token: https://statbrag.com/sign-in?next=%2Fapp%2Fagents
2. Copy this message.
3. Send it to your agent: it reads this page, adds Statbrag, then tells you how to give it your token safely and whether to restart it.

```text
Connect yourself to Statbrag, an MCP server that turns my stats into images for social media. Read https://statbrag.com/connect.md and follow the setup steps for yourself. I have an agent token: tell me how I should safely give it to you, so it stays out of this chat. When you're done, tell me if I need to restart you.
```

Agents keep secrets in different ways, so yours tells you how it takes your token. Keep the token out of the chat itself: anything typed there can end up in logs.

## The server URL

Every agent connects to Statbrag at this address:

```text
https://statbrag.com/mcp
```

## Set up your agent

### Claude.ai

1. On claude.ai or in the Claude desktop app, open Customize → Connectors.
2. Click “+”, then “Add custom connector”.
3. Name it Statbrag and paste the URL below as the MCP server URL. Keep what Claude detects: “Sign in now” and “Use Claude's published identity”. Click “Add”.
4. Click “Connect”, sign in to Statbrag and click “Allow”.
5. In a chat, click “+”, then “Connectors”, and turn Statbrag on. Ask Claude: “Use Statbrag to make a card about my week.”

```text
https://statbrag.com/mcp
```

The Free plan has room for one custom connector. On a Team or Enterprise plan, an owner adds it under Organization settings → Connectors, then you click “Connect”.

### ChatGPT

1. Turn on Developer mode in ChatGPT's settings, then add a connector with this URL and OAuth authentication. Sign in to Statbrag when ChatGPT asks, and click “Allow”. Use it in Work mode: ChatGPT's chat doesn't call custom connectors.

```text
https://statbrag.com/mcp
```

Tools that save need Developer mode, which OpenAI lists for Business, Enterprise and Edu workspaces.

### Claude Code

1. Create an agent token in Statbrag: https://statbrag.com/sign-in?next=%2Fapp%2Fagents
2. Run this in a terminal. It adds Statbrag to every project.

```text
claude mcp add --transport http --scope user statbrag https://statbrag.com/mcp --header "Authorization: Bearer <your agent token>"
```

For the agent: Run this yourself, with the single quotes so the shell leaves the variable alone: `claude mcp add --transport http --scope user statbrag https://statbrag.com/mcp --header 'Authorization: Bearer ${STATBRAG_TOKEN}'`. Tell the user to add `export STATBRAG_TOKEN="<your agent token>"` to their shell profile (such as `~/.zshrc`) in their own editor, then restart you from a new terminal. Check with `/mcp` that statbrag is connected.

### Cursor

1. Create an agent token in Statbrag: https://statbrag.com/sign-in?next=%2Fapp%2Fagents
2. Add this to ~/.cursor/mcp.json, next to any servers already there.

```text
{
  "mcpServers": {
    "statbrag": {
      "url": "https://statbrag.com/mcp",
      "headers": {
        "Authorization": "Bearer <your agent token>"
      }
    }
  }
}
```

For the agent: Add the code above to `~/.cursor/mcp.json` yourself, with `"Authorization": "Bearer ${env:STATBRAG_TOKEN}"` as the header. Tell the user to add `export STATBRAG_TOKEN="<your agent token>"` to their shell profile (such as `~/.zshrc`) in their own editor, then quit Cursor and open it from a new terminal, because it reads variables from the shell it starts in. Tell them to check that statbrag is turned on under Cursor Settings → MCP.

### Hermes

1. Create an agent token in Statbrag: https://statbrag.com/sign-in?next=%2Fapp%2Fagents
2. Add this to ~/.hermes/config.yaml, then reload MCP servers or restart Hermes.

```text
mcp_servers:
  statbrag:
    url: "https://statbrag.com/mcp"
    headers:
      Authorization: "Bearer <your agent token>"
```

For the agent: Add the code above to `~/.hermes/config.yaml` yourself, with `Authorization: "Bearer ${STATBRAG_TOKEN}"` as the header. Tell the user to add `STATBRAG_TOKEN=<your agent token>` to `~/.hermes/.env` in their own editor. Then run `/reload-mcp` if you can; otherwise tell the user to restart Hermes.

### Grok Bot

1. Create an agent token in Statbrag: https://statbrag.com/sign-in?next=%2Fapp%2Fagents
2. Send this to Grok Bot. When it shows a secret card for STATBRAG_TOKEN, paste your token there, not in the chat.

```text
Add a custom MCP server (not a catalog app) called statbrag:
- URL: https://statbrag.com/mcp
- Transport: Streamable HTTP
- Header: Authorization: Bearer <my Statbrag agent token>

Ask me for the token with a secure secret card named STATBRAG_TOKEN. I won't paste it in the chat.
Once it's connected, call statbrag's get_playbook to check it works.
```

## What to ask your agent

Copy one of these into your agent to make your first card. Do what its note says first; the note isn't part of the message.

- Note: Attach a screenshot of your Strava stats to the message first.
  Ask: "Use the screenshot I'm attaching of my Strava stats. Make a Statbrag card of how far I ran this month."
- Note: For Claude Code or Codex: they can read your token usage on your computer, with nothing to install first.
  Ask: "How many tokens did I use today, and what would they have cost at API prices? Make a Statbrag card of it."
- Note: Your agent needs access to GitHub. If it has none, paste a link to your profile.
  Ask: "Look at my GitHub commits this week and make a Statbrag card of what I shipped."
- Note: Works in any agent. Replace the part in brackets with what you shipped.
  Ask: "I just shipped [what you shipped]. Make a Statbrag card announcing it."
- Note: Attach screenshots of this week's designs, or list what you worked on.
  Ask: "Here's what I designed this week. Make a Statbrag card of it."
- Note: Paste your numbers into the message: a table, a list, a screenshot.
  Ask: "Here are some numbers from my week. Find the most interesting one and make a Statbrag card of it."

## What your agent can do

- It makes and edits cards and decks.
- It puts a photo behind a card's stats: one of yours, one from a public link, or a free stock photo. It sets which part of the photo stays in view, the overlay that keeps the stats readable, and the blur. It can also put your picture in place of your initials.
- It sends them to Buffer, which schedules posts on your social media: as drafts, at the end of your queue or at a set time.
- Whether it may schedule and post, or only save drafts, is your call. You set it on the Agents page.

## More

- [How Statbrag works](https://statbrag.com/how-it-works.md)
- [Privacy](https://statbrag.com/privacy)
- [Terms](https://statbrag.com/terms)