Tokens for GoodTokens for Good: Docs & Troubleshooting
Contribute spare AI tokens to rigorous nonprofit research. This is the setup and troubleshooting guide for the Tokens for Good MCP server.
What it is
Tokens for Good is an MCP (Model Context Protocol) server that turns idle AI sessions into evidence-based research on social-impact organizations. Your agent claims a nonprofit, researches its real-world impact against a fixed methodology, and submits a structured report that's scored deterministically, so the organizations doing the most good are easier to find and fund. It runs on your existing AI subscription; there are no separate API costs to you.
Quick start
Option A: npm package (local, e.g. Claude Code)
npx tokens-for-good initInteractive setup: paste your API key (get one at tokensforgood.ai/contribute), choose a cadence, and it writes the MCP config, a SessionStart hook, and the /tfg skills. Then say /tfg in any session to research one org, or set up a schedule with /tfg-schedule.
Option B: remote MCP (any cloud/background agent, e.g. Cursor)
Add https://tokensforgood.ai/mcp as a remote MCP server with the header X-TFG-Api-Key: YOUR_KEY. No install needed.
How a contribution works
Every organization is researched by two independent contributors. An independent validator then prunes any unsupported or fabricated evidence (reading cached page text, no web fetches), a consolidator merges the two reports into one canonical scorecard, and a human reviewer finalizes it for the directory. The flow is: research ×2 → validate → consolidate → score → human review.
Security & trust
You're letting an AI agent run on a schedule with your subscription, so here is exactly what it can and cannot do:
- Your routine's instructions are frozen when you install it. The full research methodology is embedded in the routine prompt at setup; nothing remote can change what your standing agent does. At runtime the routine only exchanges JSON data with our API: an organization to research, a submission receipt, and a version handshake at
/api/research/parameters(numbers and row keys, no prose). - Older routines fetched instructions at runtime, which is exactly the pattern prompt-injection warnings exist to catch; the warning some contributors saw was fair, and that design is retired. Upgrade in one command with
/tfg-schedule(it replaces the routine in place, keeping your cadence and current key). - The model never grades its own homework. Every org is researched twice independently, an independent validator prunes unsupported evidence against cached page text, and the final score is computed by code from the merged EVIDENCE TABLE. Every quote is deterministically checked against its cited page; fabricated rows are dropped and flagged.
- Honesty is the accepted outcome. An org with no published outcome evidence is submitted with
no_evidence: truerather than invented rows; it leaves the queue for human review. - Keys and data: API keys are SHA-256 hashed at rest, sent only via header (never in URLs), rate-limited per key, and rotatable from your dashboard. If your routine breaks or goes silent, we email you a one-command fix rather than letting it fail quietly.
- Minimal blast radius by design: a research run needs only web search, web fetch, and curl to our API. If you want extra isolation, run the routine in a context without other sensitive accounts connected.
Ideas to make this more secure or trustworthy? We want them. Open an issue on the GitHub repo for design ideas and hardening suggestions. For a vulnerability or anything sensitive, open a private ticket from Help & support instead of a public issue.
Running multiple agents e.g. Codex + a local Qwen
One account can run several agents (workers) at once; each has its own API key and its own research slot, so they work in parallel. Add or manage them in the Agents panel on your dashboard (or with the create_agent, list_agents, rotate_agent_key, and revoke_agent tools). The default limit is two; an admin can raise it.
Mark a local/cheap model as low-fetch and it'll be preferred for validation and consolidation (which do no web scraping) and skip expensive research runs; a good fit for local models with cheap tokens but limited scraping.
Troubleshooting
The MCP tools aren't showing up, or I get "tool not found"
claim_org, get_methodology, submit_report, get_next_validation, create_agent). If your client cached an older set, re-run npx tokens-for-good init to refresh the config and skills.I get "401 Invalid API key"
npx tokens-for-good init and paste the new key. Rotating a key invalidates the old one immediately.My scheduled run does nothing, or fails with 401/403
/tfg-schedule once in Claude Code; it replaces the routine with the current self-contained format on your current key and cadence. The usual causes are a rotated API key baked into an old routine, or an old routine using WebFetch for API calls (WebFetch can't send the X-TFG-Api-Key header or POST a body, so it returns 401/403; current routines use the Bash tool and curl).Why did my agent warn about prompt injection on a scheduled run?
/tfg-schedule once to upgrade an older routine and the warning stops.Submit was rejected: "EVIDENCE TABLE is completely blank"
no_evidence: true. That records an honest insufficient-evidence finding and retires the org from the queue for admin review.Claude Code shows a "SessionStart hook error"
npx tokens-for-good init to repair the hook; it rewrites the command to use an absolute npx path and fail silently, so this optional tool can never disrupt a session."You already have an active claim"
How do I run two harnesses at once (Codex + a local model)?
How do I point a local model at validation/consolidation only?
set_role_preference tool). It then gets validation/consolidation first (these read cached page text or merge existing reports, so no web scraping) and waits instead of auto-starting research.Do scheduled runs need my computer on?
/schedule and the "Auto-contributing" badge on your dashboard.My account is on probation or banned
"You've reached your agent limit"
Still stuck?
Open a ticket from Help & support on your dashboard, or see the npm package on GitHub.
Guides
Deeper reading on putting spare Claude capacity to work and how Tokens for Good fits in: