Sebora MCP

Connect Claude (web or Desktop), ChatGPT, and other MCP clients to the Sebora Partner API — run SEO/GEO audits, wait for results, and pull markdown reports from chat.

Two setups:

Mode	Best for	How
Remote MCP (recommended for web)	Claude.ai, ChatGPT Connectors	Public HTTPS URL on your Sebora app
Local MCP (stdio)	Claude Desktop on your machine	Node process in `packages/sebora-mcp`

Both use the same tools (sebora_create_audit, sebora_get_audit_report, etc.) and your Partner API key.

What you can do

Run a full SEO/GEO audit on any domain from natural language
Wait until the audit completes, then read a markdown report
List audits and check credits before starting

WARNING

Each audit consumes partner credits. Check usage before large batches.

Before you start

Requirement	Details
Partner account	Partner Portal
API key	Partner Portal → API Keys
Sebora deployed	Production with HTTPS, or local `npm run dev` for testing

Remote MCP (Claude web & ChatGPT)

Remote MCP is served from your Sebora app at:

text

https://<your-app-domain>/api/v1/mcp

Claude and ChatGPT connect from their cloud to that URL (not from your laptop). Your server must be publicly reachable over HTTPS.

1. Enable on the server

Set in .env (or hosting env vars):

bash

MCP_REMOTE_ENABLED=true
APP_URL=https://your-production-domain   # public HTTPS issuer, no trailing slash

Redeploy or restart the app. You should see two log lines: [MCP OAuth] Authorization server endpoints registered (/oauth/*, /.well-known/*) and [MCP Remote] Streamable HTTP MCP at /api/v1/mcp.

Local testing

localhost is not reachable from Claude/ChatGPT clouds. Use a tunnel (e.g. ngrok) to expose https://….ngrok.io and set APP_URL to that tunnel URL, or test with Claude Desktop (local MCP below).

2. Authentication — OAuth (no API key to paste)

Claude.ai and ChatGPT do not offer a field to paste a static partner API key. They drive an OAuth 2.1 handshake against your Sebora app:

Client fetches /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server (auto-discovered).
Client self-registers (Dynamic Client Registration, POST /oauth/register).
You're sent to /oauth/authorize — enter your Sebora partner email (same as the Partner Portal) and approve. Sebora emails you a secure sign-in link (passwordless magic link, like Partner Portal login).
Open the link from your inbox — it confirms your identity and finishes the grant, returning an authorization code to the client.
The client exchanges the code at /oauth/token (authorization code + PKCE) for an access token scoped to your partner. No keys are copied by hand.

The magic link is single-use and expires in 15 minutes. Access tokens are short-lived and refreshed automatically. (Static X-API-Key / Bearer <partner_api_key> still works for Claude Desktop / Code / curl — see Local MCP below.)

3. Claude.ai (web)

Open claude.ai → Settings → Connectors
Add custom connector (Developer mode may be required on your plan)
Server URL: https://your-production-domain/api/v1/mcp
Click Connect → Claude opens the Sebora authorize page → enter your partner email → open the emailed sign-in link to finish
Enable the connector on a new chat

Anthropic connects from their infrastructure; the URL must be public HTTPS. See Anthropic: remote MCP connectors.

4. ChatGPT

Settings → Apps & Connectors → enable Developer mode (paid plans)
Create connector
Server URL: https://your-production-domain/api/v1/mcp
Authentication: OAuth → enter your partner email and open the emailed sign-in link to authorize
Trust the application and enable the connector in chat

ChatGPT also requires a public HTTPS MCP endpoint. Tool availability depends on plan and developer mode.

5. Confirm it works

In a new chat with the connector enabled:

“What Sebora tools do you have?”
“Check my Sebora partner credits.”
“Run a full SEO audit on example.com and summarize the top issues.”

Remote troubleshooting

Issue	What to check
Connector won’t connect	`MCP_REMOTE_ENABLED=true`, valid public HTTPS `APP_URL`, firewall allows inbound
Discovery fails	`GET /.well-known/oauth-authorization-server` returns JSON with your `APP_URL` as `issuer`
No sign-in email	Email must match an active Partner Portal account; check spam; `RESEND_API_KEY` set
Sign-in link rejected	Link is single-use and expires in 15 min — restart the connection to get a fresh one
`401` after connecting	Access token expired and refresh failed — reconnect the connector
Tools missing	Full app restart after env change; check server logs
Audits stuck	`npm run dev` locally; Redis worker if `REDIS_URL` is set

Server logs (macOS): Claude may log MCP client errors locally; Sebora logs appear in your app process.

Local MCP (Claude Desktop)

For Claude Desktop only — runs a local Node MCP process (stdio). Not used on claude.ai.

Install

bash

cd packages/sebora-mcp
npm install
npm run build

Or from repo root: npm run mcp:sebora:build

Entrypoint: packages/sebora-mcp/dist/index.js (use an absolute path in config).

Configure Claude Desktop

Settings → Developer → Edit Config
Add under mcpServers:

json

{
  "mcpServers": {
    "sebora": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/sebora-agentic/packages/sebora-mcp/dist/index.js"],
      "env": {
        "SEBORA_API_URL": "https://your-production-url",
        "SEBORA_API_KEY": "your_partner_api_key"
      }
    }
  }
}

Example file: packages/sebora-mcp/claude_desktop_config.example.json

Fully quit and reopen Claude Desktop.

Config paths:

OS	File
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Cursor (optional)

Copy .cursor/mcp.json.example → .cursor/mcp.json, set SEBORA_API_KEY, restart Cursor, enable sebora under Settings → MCP.

Environment variables

Remote (on Sebora server)

Variable	Required	Description
`MCP_REMOTE_ENABLED`	Yes (`true`)	Enables `/api/v1/mcp` and the OAuth server (`/oauth/`, `/.well-known/`)
`APP_URL`	Yes	Public HTTPS base URL / OAuth issuer (no trailing slash)
`PARTNER_JWT_SECRET`	No	Signs OAuth access tokens (falls back to `SESSION_SECRET`)

Local stdio (`packages/sebora-mcp`)

Variable	Required	Default	Description
`SEBORA_API_KEY`	Yes	—	Partner API key
`SEBORA_API_URL`	No	`http://localhost:5000`	Sebora API base URL

Never commit API keys to git.

Tools reference

Tool	Description
`sebora_get_usage`	Credits and audit counts
`sebora_create_audit`	Start audit (`domain`, `audit_tier`, `locale`)
`sebora_get_audit_status`	Status and `progress_log`
`sebora_list_audits`	List with filters
`sebora_wait_for_audit`	Poll until done/failed
`sebora_get_audit_report`	Markdown (default) or JSON

Recommended flow

sebora_get_usage
sebora_create_audit → { "domain": "example.com" }
sebora_wait_for_audit → { "audit_id": "..." }
sebora_get_audit_report → { "format": "markdown" }

Or sebora_get_audit_report with "wait_if_running": true.

Audit tiers

Tier	Use
`quick_scan`	Fast, lowest credits
`technical`	Technical SEO
`full_seo`	Default balanced audit
`deep`	Deeper analysis
`expert`	Highest tier

Development

bash

# Build MCP package
npm run mcp:sebora:build

# Run Sebora with remote MCP
MCP_REMOTE_ENABLED=true APP_URL=http://localhost:5000 npm run dev

Package source: packages/sebora-mcp/README.md

Partner API: /api/v1 (same backend as MCP tools)
Partner Portal: /partner

Sebora MCP ​

What you can do ​

Before you start ​

Remote MCP (Claude web & ChatGPT) ​

1. Enable on the server ​

2. Authentication — OAuth (no API key to paste) ​

3. Claude.ai (web) ​

4. ChatGPT ​

5. Confirm it works ​

Remote troubleshooting ​

Local MCP (Claude Desktop) ​

Install ​

Configure Claude Desktop ​

Cursor (optional) ​

Environment variables ​

Remote (on Sebora server) ​

Local stdio (packages/sebora-mcp) ​

Tools reference ​

Recommended flow ​

Audit tiers ​

Development ​

Related ​

Sebora MCP

What you can do

Before you start

Remote MCP (Claude web & ChatGPT)

1. Enable on the server

2. Authentication — OAuth (no API key to paste)

3. Claude.ai (web)

4. ChatGPT

5. Confirm it works

Remote troubleshooting

Local MCP (Claude Desktop)

Install

Configure Claude Desktop

Cursor (optional)

Environment variables

Remote (on Sebora server)

Local stdio (`packages/sebora-mcp`)

Tools reference

Recommended flow

Audit tiers

Development

Related