Connect AgentSEO to Claude Code when you need Google results for a specific query, market, and device. Start with one search results check and confirm you have a usable response before building a workflow around it.
Copy the setup first, validate one live workflow, then decide whether this path belongs in docs, automation, or your agent runtime.
Before you start
You need Claude Code and an AgentSEO server-side API key. The free sample in the Claude SEO guide works with the bundled files and needs no AgentSEO account.
Use This Guide For
Open the configuration, see a sample response, or review the API quickstart.
Setup
Jump straight into the setup snapshot and implementation plan if the runtime is already chosen and you just need it working.
Proof
Use the example and output sections when the real question is whether this integration produces the right shape for your team or client.
Context
Go back to quickstart or API docs if this page clarified the runtime but you still need the shared request model and auth contract.
Core workflows
Setup snapshot
{
"mcpServers": {
"agentseo": {
"type": "http",
"url": "https://www.agentseo.dev/mcp",
"headers": {
"Authorization": "Bearer ${AGENTSEO_API_KEY}",
"x-workflow-id": "claude-seo-starter"
}
}
}
}Discovery shows the available tools. Live execution uses your AgentSEO key and consumes credits according to the tool.
Implementation plan
Create an AgentSEO API key without browser domain restrictions. Set AGENTSEO_API_KEY in the shell environment that will launch Claude Code.
Save the sample as .mcp.json in your project root. If the file already exists, add the agentseo entry to its mcpServers object.
Start Claude Code in that directory, approve the project server if prompted, and open /mcp to check discovery.
Run the example below and inspect the returned result or job status.
Output shape
Limits
Visual flow
One query gives you a bounded way to check the connection and review the evidence.
User asks for SERP triage or page opportunity analysis.
Claude calls analyze_serp or another AgentSEO tool.
Check the existing job if the result is queued.
Read the result and confirm it supports the proposed action.
Concrete example
Ask for one query and keep the result context with the recommendation.
Prompt for Claude Code
Use AgentSEO's analyze_serp tool for "claude seo".
Use United States, en, and desktop.
If queued, keep the job ID and check its status.
Show up to three direct result URLs and the intent they support.
If a redirect hides a destination, report its rank and title and mark the destination unknown.What to check in the result
Completed: inspect the SERP features and any direct result URLs.
Queued: pass the returned ID as job_id to agentseo_job_status.
Failed or pending: report the current state before drawing conclusions.Related reading
Use the linked posts to decide where Claude Code should fit, what should stay manual, and how to turn a useful loop into something the team can reuse.
Try the decision workflow with bundled sample data before connecting live results.
Start here if you want the safe operating boundary before you let Claude Code become part of a real marketing workflow.
Use this when you want to move from one useful prompt into a loop the team can actually keep and monitor.
Use this to decide when Claude should inspect real state over MCP and when a drafting-only flow is still enough.
Use this when the workflow is getting stable enough that a small internal tool would save more time than another saved prompt.
FAQ
Tool execution needs a valid AgentSEO key. Check that AGENTSEO_API_KEY is available in the environment that launched Claude Code and that the Authorization header uses Bearer followed by the key.
For a 403, check whether the key was revoked, expired, or has an allowed domain list. For a 402, check the account credit balance before retrying.
Use agentseo_job_status with the returned job ID. Use the evidence once the job completes, or report the failure if the job ends without a result.