Troubleshooting

Most failures are auth, the wrong MCP URL, or no project data yet.

401 and agent_auth_required

The first call without a Bearer token returns 401 and JSON with error: "agent_auth_required". That is correct. The body includes mcpUrl, resourceMetadataUrl, agentSettingsUrl, and nextSteps.

If the client never opens a login window:

• Remove any extra Authorization key from MCP config
• Use only { "url": "<MCP URL from Agent settings>" }
• Reload the client, then click Connect

Do not test with plain curl unless you include Authorization: Bearer <oauth-access-token>.

See Auth.

Token was valid, then 401 again

Expired or revoked token, or you mixed localhost and production URLs. Revoke at /account/agents, copy the URL again from /p/{projectSlug}/settings/agent, reconnect.

403

You signed in, but that user cannot access the requested project. MCP is scoped to the same access as the website. Confirm the account in the OAuth window is the one that owns (or was invited to) the project.

MCP tools do not have a separate “admin only” gate. If the dashboard opens the project, tools should too.

Missing or unknown project

aiseo_list_projects is empty → create a project in the app.

Tool says project not found → the slug is wrong or you used a different user. Call aiseo_list_projects again and pick a slug from the list.

Empty sources/prompts on a brand-new project → scans have not finished. The payload includes dataStatus: "no_data" and nextSteps. Wait; do not treat that as a broken connection, and do not scrape the public site.

dataStatus: "empty_filter" means the project has data but the filter (status, domain, brand) matched nothing. Retry without the filter.

Reconnect checklist

1. Open /p/{projectSlug}/settings/agent
2. Copy MCP JSON
3. Save it in the client (Cursor: .cursor/mcp.json or Settings → MCP)
4. Reload the window
5. Connect / Authorize
6. Sign in and Allow
7. Call aiseo_list_projects

If the Agent settings page itself says agent_auth_required, the client is still using a stale session. Reconnect rather than retrying the same token.