Quickstart: AI Agent Integration

Connect your AI coding agent (Cursor or Claude Code) to SoloKit SEO in 3 steps. Once set up, you can ask your agent to find and fix SEO issues directly — no manual API calls needed.

---

Step 1: Generate an API Key

Go to Dashboard → API Keys and click Create Key.

Important: Copy the full key (sk_live_xxx) immediately after creation. It is only shown once.

---

Step 2: Connect Your Agent

Choose the method that fits your setup.

Option A: HTTP (Recommended — no installation required)

No need to clone the repo or run any process. Just point your agent at the MCP endpoint with your API key.

Cursor — create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "solokit-seo": {
      "type": "streamableHttp",
      "url": "https://seo.solokit.run/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_key"
      }
    }
  }
}

"type": "streamableHttp" is required. Without it, Cursor throws an Invalid URL protocol error.

Claude Code — edit ~/.claude.json:

{
  "mcpServers": {
    "solokit-seo": {
      "url": "https://seo.solokit.run/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_key"
      }
    }
  }
}

Restart your agent after saving. The solokit-seo tools will appear automatically.

---

Option B: Skill URL (Zero config)

If you don't want to configure MCP upfront, paste this into any agent chat:

Read https://seo.solokit.run/SKILL.md and follow the instructions to fix my SEO issues.

The agent fetches the skill file, learns the workflow on the spot, and guides you through the setup if needed.

---

Option C: Coze skill (inside Coze / 扣子)

If you run your agent on the Coze platform, install the official SoloKit skill:

1. In Coze's skill marketplace, search for SoloKit SEO 助手 (or open its skill detail page).
2. Click Add to an agent — create one or pick an existing agent.
3. On first use, enter your own API key when prompted (each user fills in their own key; they don't interfere).
4. Your Coze agent can then query sites, SEO issues, action plans, and run GEO probes directly.

The skill wraps SoloKit's public REST API (seo.solokit.run/api/public/**). Its agent talks to the API directly via the skill's bundled script — no MCP or CLI needed.

---

Option D: Command-line CLI (terminal / scripts / agents)

@solokit/cli wraps the SoloKit API into an agent-friendly CLI — ideal for terminal scripts, cron jobs, and shell-type agents like Claude Code, Codex, or Cursor.

# Install globally (or just use npx, no install needed)
npm i -g @solokit/cli

# Set your API key (or pass it with --key)
export SOLOKIT_API_KEY=sk_live_your_key

# Common commands (all support --json for agent parsing)
solokit seo whoami                        # identity & quota
solokit seo sites list                    # site list
solokit seo issues list --priority high   # high-priority issues
solokit seo plans list                    # action plans

Agent-friendly contract: exit codes 0=OK / 1=ERROR / 2=USAGE / 3=AUTH / 4=QUOTA / 5=UPSTREAM, and failures emit {error,message,hint,docs} so agents can decide the next step.

---

Option E: Local process (offline / self-hosted)

For environments without internet access, clone the repo and run the MCP server locally.

# Get your project path
pwd
# e.g. /Users/alice/solokit

Cursor / Claude Code config:

{
  "mcpServers": {
    "solokit-seo": {
      "command": "node",
      "args": ["/Users/alice/solokit/mcp-server/dist/index.js"],
      "env": {
        "SOLOKIT_API_KEY": "sk_live_your_key",
        "SOLOKIT_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

---

Step 3: Talk to Your Agent

Once connected, use natural language — no commands needed:

Show me all high-priority SEO issues for my sites

What's wrong with site 2? Show me the current value and what it should be

Mark issue 42 as fixed

The agent calls the platform API automatically and returns structured results.

---

Available MCP Tools

After connecting, your agent can call:

UI usage by scenario: AI Answer Probes. Do not merge the four rates into one score.

---

Example Workflow

You:   List all high-priority SEO issues for site 1.
Agent: [calls list_seo_issues] Found 3 issues:
       - title: 92 chars (max 60) on /about
       - description: missing on /pricing
       - h1: multiple h1 tags on /blog

You:   Fix the title issue and mark it as done.
Agent: [edits the file, then calls update_issue_status]
       Done. Title shortened to 54 chars and marked as completed.

---

REST API (without MCP)

You can also call the public API directly with any HTTP client:

# List sites
curl -H "Authorization: Bearer $SOLOKIT_API_KEY" \
  https://seo.solokit.run/api/public/sites

# Get pending high-priority issues
curl -H "Authorization: Bearer $SOLOKIT_API_KEY" \
  "https://seo.solokit.run/api/public/seo-issues?priority=high&status=pending"

# Mark an issue as fixed
curl -X PATCH \
  -H "Authorization: Bearer $SOLOKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed", "note": "Shortened title to 54 chars"}' \
  https://seo.solokit.run/api/public/seo-issues/42

Full API reference: GET /api/openapi

---

Troubleshooting

---

Next Steps

• API Key Management — manage permissions and expiry
• AI Answer Probes — mention / recommend / cite by scenario
• Agent Management — configure AI analysis agents
• Site Management — add and manage your websites