MCP tools
Endpoint: https://polis.sh/api/mcp (Streamable HTTP). Auth: Authorization: Bearer <api_key>, or OAuth 2.1 for connectors that require it (Claude.ai / ChatGPT — see Connect via OAuth).
| Tool | Cost | Purpose |
|---|---|---|
polis_account | free | Subscription status, included allowance left, overage used, usage cap. If inactive, returns plan checkout URLs (human path) and top-up pack pay URLs (agent path). |
polis_topup | the pack price | Mint a Stripe Checkout for a one-off token pack. Agent-pay: complete pay_url directly via the Stripe Agent Toolkit + Link wallet / SPT, or relay to a human. Tokens are credited on Stripe settlement. Pack sizes: small $5/1k, medium $20/4k, large $50/12.5k (Pro discount), scale $200/55k (Scale discount). |
polis_estimate | free | Token + USD estimate for a prospective run and how it splits vs. the spend limit. |
polis_test | charged up front | Start a persona test. Returns a run_id. Refunded automatically if the run fails before a report. |
polis_status | free | Progress for a run_id (reactions done / total, done flag). |
polis_report | free | The completed deliverable + aggregate stats + sample verbatim reactions. |
polis_ask | charged | After a complete run, ask a follow-up of one persona, an archetype, a segment, or the whole panel. Multi-turn via thread_id. |
polis_thread | free | Read a follow-up thread transcript + status (poll a background panel ask). |
polis_test inputs: content_type (text|tweet|linkedin|markdown|url), content (unless url), url + url_mode (copy|visual) for url, optional audience, persona_count (10-1000, default 100), detail (snapshot|standard|deep, default standard).
polis_ask inputs: run_id, target (persona|archetype|segment|panel), persona_id/archetype/segment as needed, question, optional thread_id to continue. Panel asks run in the background — poll polis_thread.
Every tool response includes a _usage block (plan, included tokens remaining, in_overage, overage $, cap, cap remaining) so you always know where you stand.
Runs are asynchronous. Always: polis_estimate → polis_test → poll polis_status → polis_report → optionally polis_ask.
All docs
- What Polis is: The concept, inputs, and what you get back.
- Agent quickstart: Connect, get a key, run a test, read the report.
- How to run a test: The workflow, a worked example, and how to read the report.
- Test options reference: Every input, every variation, and the full report schema.
- MCP tools (you are here): Every tool, its inputs, and cost.
- Detail levels & follow-up: Richer per-persona output, and asking personas follow-ups.
- Pricing & billing: Polis tokens, plans, free trial, metered usage, spend limit.
- Connect via OAuth (Claude, ChatGPT): Optional OAuth 2.1 for connectors that don't take a raw API key.
- Discovery & well-known endpoints: How agents and clients discover Polis.
Polis docs index · Full machine-readable index (llms.txt) · Everything inlined (llms-full.txt)