Wire yeet into Claude or Cursor in 5 Minutes (MCP Setup)

yeet-seo ships a full Model Context Protocol (MCP) server: yeet-seo-mcp, currently at v0.7.0. It exposes 106 tools covering indexing, autonomous fixes, keyword and backlink research, AEO/citation tracking, and outcome analytics — the same surface used internally by the autonomy engine. If you run Claude Code, Claude Desktop, or Cursor, you can give either one direct, authenticated access to a live workspace in about five minutes. This guide is the setup path; for the primitive both humans and agents call most, see the check API guide.

The distinction that matters for this audience: yeet-seo is not a dashboard with an API bolted on afterward. The MCP server and the REST API in the check API guide are two transports over the same underlying operations — a card, a check, an autonomy setting is the same object whether your agent reaches it through run_check or POST /api/v1/check. That matters when you're deciding where to put logic: an interactive Claude Code session is usually better served by MCP tools (structured, typed, discoverable in the client's tools panel), while a CI job or a service with its own HTTP client often prefers the REST surface directly. Both hit the same rate limits and the same credit ledger, so mixing them in one workspace is safe.

Step 1: get an API key

Log into yeet.ani.computer, go to Settings → API Keys & MCP, and create a key. MCP access requires a Pro plan or higher (see pricing for plan limits). Keys are issued with the yseo_ prefix and shown once — store it in a secrets manager or your shell's env, not in a repo.

Keys carry one of two scopes:

• read — workspace overview, checks, outcomes, rank/keyword/backlink data, AEO citations
• write — everything read does, plus submitting URLs, running checks/agent jobs, approving hypotheses, card actions, and autonomy changes

Per-key rate limits apply; if you're wiring up multiple agents (a nightly CI job and an interactive Claude Code session, say), issue separate keys so one doesn't throttle the other.

Step 2: drop the config block

Add this to your MCP client config (claude_desktop_config.json for Claude Desktop, your Claude Code MCP settings, or Cursor's mcp.json):

{
  "mcpServers": {
    "yeet-seo": {
      "command": "npx",
      "args": ["-y", "yeet-seo-mcp"],
      "env": {
        "YEET_SEO_API_KEY": "yseo_your_key_here"
      }
    }
  }
}

Restart the client. On next launch it spawns the server over stdio and lists all 106 tools — check your client's MCP/tools panel to confirm the handshake.

stdio vs. Streamable HTTP

stdio is the default transport and what most desktop clients expect. If you're running the server as a shared process (a CI runner, a container sidecar, multiple agents hitting one instance) set:

{
  "env": {
    "YEET_SEO_API_KEY": "yseo_your_key_here",
    "YEET_SEO_MCP_TRANSPORT": "http"
  }
}

which serves Streamable HTTP instead, so multiple clients can connect to one long-lived process rather than each spawning its own.

Step 3: the first-session tour

Once connected, start with the capability menu so you (and the user) know what yeet can do:

Tool / resource	Purpose
help / yeet-seo://help	User-facing menu: skills, say-this phrases, recommended flow
get_workspace_overview	Connected properties, autonomy mode, open cards, recent checks
run_skill	High-level workflows: onboard, scan, index, optimize, create, seo_report
run_check / get_check	Full check cycle (indexing, verifier, AEO, investigation)

A reasonable first prompt: "call help and show me the menu, then get_workspace_overview, then run_skill onboard for my site." Ask "what can yeet do" anytime to re-show the menu. Docs: Continuous Optimize. Skill flow: onboard → scan → index → optimize → create → seo_report.

Beyond skills, the tool set breaks into families worth knowing: submit_urls (bulk indexing, ≤50 URLs per call), run_agent_job (kinds: seo_agent, investigator, content_ideator, properties_refresh, insights_refresh, full_refresh), set_autonomy, get_outcome_stats, get_ai_citations / track_prompt / get_prompt_ranks / analyze_page_aeo / generate_llms_txt for AEO work, get_search_performance, keyword/backlink/rank/competitor research suites, approve_hypothesis / dismiss_hypothesis, and the card tools (auto_apply_card and friends) that drive the PR pipeline covered in the auto-apply deep dive.

Reading before writing, in practice

A useful discipline for any agent wired into a live workspace: run the read-scoped tools first, every session, before touching anything mutating. get_workspace_overview tells you the current autonomy mode and whether auto-merge is on — information that changes what a subsequent run_check is actually going to do unattended. get_outcome_stats (covered in depth in the outcome priors guide) tells you whether the subcategories you're about to touch have a track record worth trusting. Only after both of those does it make sense to call run_check, and only after a check surfaces something does it make sense to reach for card or hypothesis tools. Skipping straight to writes on a freshly connected agent is the most common way to get surprised by state you didn't know existed.

Device-flow pairing for headless CLI agents

If your agent runs somewhere without a browser to click through — a CI runner, a remote box — yeet-seo supports device-flow pairing so you can authorize the key from any browser and have the CLI agent pick it up without ever seeing a login page. This is the recommended path for the CI patterns in the agentic workflows guide, where the "agent" is a scheduled job with no interactive session.

Troubleshooting the handshake

If the tools panel comes up empty after a restart, check these in order: the key still has the yseo_ prefix intact (copy/paste sometimes truncates it), the key hasn't been revoked from Settings, the workspace's plan still has MCP access active, and npx can actually reach the registry (a corporate proxy or offline cache can silently swallow the -y install). A key with only read scope will connect fine and list all 106 tools — the failure only shows up later, as an error, the first time a write-scoped tool like run_check or submit_urls is actually called.

What the agent can and can't do out of the box

A connected MCP client with a write-scoped key can run checks, submit URLs, and open PRs — but it cannot merge them or flip autonomy to aggressive modes unless the workspace's autonomy settings allow it. That's a deliberate two-key gate: the API key controls what the agent is capable of calling, and the autonomy mode controls what happens automatically without a human approving each card. Read the autonomy modes guide before wiring an agent into anything beyond propose_only, and how yeet verifies fixes to understand what "safe" means before a fix is marked verified.

For full endpoint and tool documentation beyond this quick tour, see the docs.

Quick FAQ

Q: Does the MCP server work with a read-only key?
A: Yes — all read tools work, but anything that mutates state (submit_urls, run_check, card actions, set_autonomy) requires a write-scoped key and will error otherwise.

Q: Can I run the MCP server against multiple workspaces from one machine?
A: Yes, define multiple entries under mcpServers with different names and different YEET_SEO_API_KEY values, one per workspace.

Q: What plan do I need?
A: Pro ($29/mo) unlocks MCP access, 60 credits/month, 3 sites, and 200 submissions/day. Agent ($99/mo) raises that to 300 credits, 10 sites, 1000 submissions/day, and unlocks aggressive autonomy — see pricing.