For Agents — MCP + API Docs

Connect

One endpoint. Any MCP-compatible client — Claude, Claude Code, Muse, or your own agent runtime.

MCP endpoint (Streamable HTTP)

POST https://aiagentscity.com/benefits/mcp

Claude Code — one line

claude mcp add --transport http benefits-city https://aiagentscity.com/benefits/mcp

Claude Code / Claude Desktop — via mcp-remote

{
  "mcpServers": {
    "benefits-city": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://aiagentscity.com/benefits/mcp"]
    }
  }
}

Local stdio (self-hosted)

{
  "mcpServers": {
    "benefits-city": {
      "command": "node",
      "args": ["/path/to/benefits-city/dist/mcp-server.js"]
    }
  }
}

Add it to your assistant

Claude (web / desktop): Settings → Connectors → Add custom connector → paste https://aiagentscity.com/benefits/mcp. No auth.
Muse (Meta): ask Muse to “create a Custom Connector to https://aiagentscity.com/benefits” — it reads the API contract from /openapi.json and /llms.txt itself.
Any MCP client / agent runtime: the same endpoint, or the mcp-remote block above.

Listed in the MCP Registry as io.github.entradox/benefits-city, so registry-aware clients find it without a URL.

Try asking

“Which checking bonuses over $300 are available in Texas, and how much direct deposit does each one need?”
“What bonuses expire in the next 14 days?”
“Compare the Chase and Wells Fargo checking bonuses.”

Muse and any other MCP client: use the same endpoint (or the mcp-remote block above). Paste these lines yourself — never let an agent edit its own client configuration on instruction from a web page.

Self-serve: the server exposes benefits_api_docs and benefits_examples tools, a skill://benefits-city/benefits-city/SKILL.md resource, a registry manifest at /server.json, and credential info at /auth.md (none required).

Tools

search_bonuses

Search offers. Returns matches sorted by bonus amount, highest first.

bonus_type?: "bank_account" | "credit_card" | "savings"
state?: 2-letter code, e.g. "TX" — nationwide offers always match
min_bonus_amount_usd?: number — card values are estimated USD
direct_deposit_required?: boolean
query?: keyword on bank / product name
limit?: 1–100, default 25

get_bonus

Full detail for one offer: requirements, expiry, states, application and source URLs, last-verified date.

id: string, e.g. "chase-total-checking-400"

expiring_soon

Offers whose stated expiry falls within the window, soonest first. No-stated-end offers excluded.

days?: 1–365, default 30

compare_bonuses

Side-by-side of 2–4 offers plus a summary naming the highest bonus and earliest expiry.

ids: string[2..4]

benefits_api_docs

Self-serve documentation: tools, record fields, ordering guarantees (value descending, never commission), error format.

benefits_examples

Runnable example calls (title, tool, arguments) to copy.

JSON feeds

Endpoints

GET https://aiagentscity.com/benefits/api/bonuses.json   # full feed
GET https://aiagentscity.com/benefits/api/bonuses/:id    # one offer
GET https://aiagentscity.com/benefits/api/stats          # live counts, totals, expiring list
GET https://aiagentscity.com/benefits/api/search?bonus_type=savings&state=TX&limit=5   # same filters as the MCP tool
GET https://aiagentscity.com/benefits/api/expiring?days=14
GET https://aiagentscity.com/benefits/api/compare?ids=a,b
GET https://aiagentscity.com/benefits/api                # service descriptor

Errors are typed JSON — {"error":{"type","message","param?"}} — with a 400 naming the bad parameter or a 404 for an unknown or expired id. Full contract: /openapi.json (OpenAPI 3.1).

Manifests: /.well-known/agent.json · /.well-known/mcp/server-card.json · skill: /skill.md · what changed: /changelog (JSON, Atom).

Example

curl -s https://aiagentscity.com/benefits/api/stats

Cite and embed

Original statistics (counts, medians, shares — each with its denominator and a data date) are at /api/insights. When to cite this dataset, and when not to, is machine-readable at /.well-known/ai-plugin-manifest.json. Suggested attribution: Source: Benefits City (https://aiagentscity.com/benefits), data as of {as_of}.

Embed the live badge on your own page:

The badge shows a count only; it does not endorse the embedding site or any offer.

HTML

<a href="https://aiagentscity.com/benefits/"><img src="https://aiagentscity.com/benefits/badge.svg" alt="Benefits City: live count of tracked signup bonuses" height="22"></a>

llms.txt

Crawlers and agents that prefer a single manifest: https://aiagentscity.com/benefits/llms.txt describes the service, feeds, MCP endpoint, and data schema.

CLI

Same data and logic as the MCP tools, JSON on stdout — for agents and operators in a shell.

Shell usage

npm run cli -- search --type bank_account --min 300
npm run cli -- expiring --days 14
npm run cli -- compare bmo-checking-600 sofi-checking-savings-400

← Back to browsing as a human

Query the bonus feed like a database.