# ChatSEO — Full reference for AI agents

> Expanded reference for LLMs and coding agents. ChatSEO is an AI SEO agent exposing a remote MCP server at `https://api.chatseo.app/mcp` (OAuth 2.1) with 34 tools for managing sites, conversations, projects, todos, integrations, and artifacts.

---

## What ChatSEO does

ChatSEO is a conversational SEO agent that:
- Connects to Google Search Console (GSC) and Google Analytics to analyze a site's actual performance
- Audits pages, generates content briefs, writes articles, and produces technical SEO reports
- Surfaces ranking opportunities, identifies keyword gaps, and prioritizes fixes
- Persists memory across conversations (business context, target audience, competitors, tone of voice)

Public website: `https://chatseo.app`
API root: `https://api.chatseo.app`

---

## MCP server

**Endpoint:** `https://api.chatseo.app/mcp`
**Transport:** Streamable HTTP (MCP spec 2025-06-18+)
**Auth:** OAuth 2.1 (bearer JWT), discovery via `https://api.chatseo.app/.well-known/oauth-protected-resource/mcp`
**Plan requirement:** Pro subscription (feature flag `API_MCP`)

### Install in Claude Desktop, Claude Code, Cursor, VS Code

Add to your MCP config (e.g. `~/.claude/claude_desktop_config.json`, `.cursor/mcp.json`, or `.mcp.json`):

```json
{
  "mcpServers": {
    "chatseo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.chatseo.app/mcp"]
    }
  }
}
```

On first use, `mcp-remote` will open a browser window for OAuth authentication against ChatSEO. Sign in with the Pro account you want the agent to act on behalf of.

### Install in ChatGPT

ChatGPT supports remote MCP servers for Pro, Team, and Enterprise accounts. In Settings → Connectors → Add custom connector:
- **URL:** `https://api.chatseo.app/mcp`
- **Auth:** OAuth (ChatGPT will run the flow automatically)

### Server card

Machine-readable metadata: `https://chatseo.app/.well-known/mcp/server-card.json`

---

## Tool catalog (34 tools)

### Organizations (3)
- `list_organizations` — List organizations the authenticated user belongs to.
- `set_organization` — Set the active organization for the session.
- `get_credits` — Return remaining credits for the active organization.

### Sites (6)
- `get_gsc_sites` — List Google Search Console properties accessible via the organization's GSC integrations.
- `list_sites` — List sites in the active organization. Args: `limit`, `offset`.
- `get_site` — Get a site by ID.
- `create_site` — Create a new site. Args include domain, language (`fr` | `en`), GSC/GA linkage.
- `update_site` — Update an existing site.
- `delete_site` — Delete a site and its data.

### Conversations (7)
- `send_message` — Send a message to ChatSEO in a new or existing conversation. Returns streamed response + artifacts.
- `list_conversations` — List conversations for the active organization.
- `update_conversation` — Update conversation metadata (title, project).
- `get_conversation_messages` — Fetch full message history for a conversation.
- `share_conversation` — Create a public share link for a conversation.
- `get_share_status` — Return current share status and public URL.
- `revoke_share` — Revoke an existing share link.

### Projects (5)
- `list_projects` — List projects in the active organization.
- `get_project` — Get a project by ID.
- `create_project` — Create a project.
- `update_project` — Update a project.
- `delete_project` — Delete a project and all its conversations.

### Todos (5)
- `list_todos` — List todos (filterable by project, site, status).
- `get_todo` — Get a todo by ID.
- `create_todo` — Create a todo with title, description, priority, due date.
- `update_todo` — Update a todo.
- `delete_todo` — Delete a todo and its subtasks.

### Integrations (5)
- `list_integrations` — List integrations (GSC, GA) for the active organization.
- `get_integration` — Get a specific integration.
- `delete_integration` — Delete an integration.
- `link_integration_to_site` — Bind an integration to a site.
- `unlink_integration_from_site` — Unbind an integration from a site.

### Artifacts (3)
- `list_artifacts` — List artifacts attached to a conversation (documents, briefs, articles, code).
- `get_artifact` — Get a single artifact by ID.
- `update_artifact` — Update an artifact's title or content.

---

## Authentication details

- **Issuer:** `https://api.chatseo.app/auth`
- **Audience:** `https://api.chatseo.app/mcp`
- **JWKS:** `https://api.chatseo.app/auth/jwks`
- **Resource metadata:** `https://api.chatseo.app/.well-known/oauth-protected-resource/mcp`
- **OpenID config:** `https://api.chatseo.app/.well-known/openid-configuration`

Unauthenticated requests receive a `401` with `WWW-Authenticate: Bearer realm="mcp", resource_metadata="..."` so MCP-aware clients can auto-bootstrap the OAuth flow.

---

## Operating notes for agents

- If any tool returns `No active organization`, call `list_organizations` then `set_organization`. If there is exactly one organization, pick it silently. Never ask the end-user to resolve this.
- `send_message` is the workhorse for running ChatSEO analyses — prefer it over composing prompts externally when the user wants a product-grade SEO answer (it runs the full agent pipeline with GSC/GA tools).
- Tools annotated `readOnlyHint: true` are safe to call speculatively; others mutate state.
- Rate limits and credit consumption apply per organization. Check `get_credits` before large batched operations.

---

## Contact

- Support: support@chatseo.app
- Website: https://chatseo.app
- Status and changelog: https://chatseo.app/blog