Robynn MCP Server

Remote MCP (Model Context Protocol) server for the Claude Connectors Directory. Deployed on Cloudflare Workers at mcp.robynn.ai.

Users connect by clicking "Robynn" in Claude's directory, authenticating via OAuth, and immediately getting brand-aware marketing tools — zero install, works on web, desktop, and mobile.

Architecture

┌──────────────────────────────────────────────────────────────────┐
│  Claude (Web / Desktop / Mobile / Code)                          │
│  User clicks "Robynn" in Connectors Directory                    │
└──────────────┬──────────────────────────────────────┬────────────┘
               │ 1. OAuth 2.0 flow                    │ 3. Tool calls
               ▼                                      ▼
┌──────────────────────────────────────────────────────────────────┐
│  Cloudflare Worker — mcp.robynn.ai                               │
│                                                                  │
│  ┌─────────────────────┐  ┌────────────────────────────────────┐ │
│  │  OAuthProvider       │  │  McpAgent (Durable Object)        │ │
│  │  /authorize → login  │  │  /mcp — Streamable HTTP           │ │
│  │  /token    → tokens  │  │  /sse — SSE transport             │ │
│  │  /register → DCR     │  │  24 tools + MCP Apps UI           │ │
│  └─────────┬───────────┘  └──────────────┬─────────────────────┘ │
│            │                              │                      │
│            │  KV Store (OAuth state)      │                      │
│            └──────────────────────────────┘                      │
└──────────────────────────────────┬───────────────────────────────┘
                                   │ 2. API calls (Bearer token)
                                   ▼
┌──────────────────────────────────────────────────────────────────┐
│  robynnv3 (SvelteKit) — robynn.ai                                │
│  /api/cli/context/[scope]  — Granular brand context              │
│  /api/cli/mcp/brand-context/search — Query-focused brand context │
│  /api/cli/usage            — Token balance                       │
│  /api/agents/cmo/*         — CMO threads/runs                    │
│  /oauth/authorize          — OAuth consent page                  │
│  /api/oauth/token          — Token exchange                      │
└──────────────────────────────────────────────────────────────────┘

Tools

| Tool | Category | Execution backend | Inline MCP App UI | |---|---|---|---| | robynn_brand_context | Brand context | Direct robynnv3 context API | No | | robynn_brand_context_search | Brand context | Direct robynnv3 MCP-safe brand-context search API | No | | robynn_status | Status | Direct robynnv3 status API | No | | robynn_usage | Status | Direct robynnv3 usage API | No | | robynn_conversations | Thread management | robynnv3 CMO thread list/create endpoints | No | | robynn_create_content | CMO execution | robynnv3 CMO thread/run pipeline, defaulting to cmo_v2 unless env overrides it | No | | robynn_research | CMO execution | robynnv3 CMO thread/run pipeline, defaulting to cmo_v2 unless env overrides it | No | | robynn_assist | CMO execution | robynnv3 CMO thread/run pipeline with caller-provided assistant routing hints and preserved thread history | No | | robynn_cmo_agent | CMO execution | robynnv3 MCP-safe CMO execution route | No | | robynn_run_status | Thread management | Direct robynnv3 CMO run status endpoint for long-running content/research jobs | No | | robynn_campaign_creator | Campaign strategy | robynnv3 MCP-safe marketing campaign route with Rory artifact persistence and unlisted report URLs for Robynn prospecting | No | | robynn_campaign_status | Campaign strategy | Direct robynnv3 marketing campaign status route for pending or completed campaign runs with report URLs on completion | No | | robynn_geo_analysis | Intelligence | GEO proxy in robynnv3 -> LangGraph geo_researcher by default | Yes | | robynn_seo_opportunities | Intelligence | SEO proxy in robynnv3 -> LangGraph seo_researcher -> seo_researcher_v5 | Yes | | robynn_competitive_battlecard | Intelligence | Direct LangGraph competitor_intelligence_v1 plus Supabase battlecard readback | Yes | | robynn_brand_book_status | Brand book | Direct robynnv3 brand-book export and changelog services | Yes | | robynn_brand_book_gap_analysis | Brand book | Direct robynnv3 brand-book adapter logic | No | | robynn_brand_book_strategy | Brand book | Direct robynnv3 brand-book adapter logic | Yes | | robynn_brand_reflections | Brand book | Direct robynnv3 changelog/reflection query logic | No | | robynn_publish_brand_book_html | Brand book | Direct robynnv3 export aggregation and HTML generation | No | | robynn_website_audit | Website intelligence | robynnv3 prospect-audit flow -> LangGraph cmo_audit_v1, returning the unlisted designed /audit/{slug}/{token} page | Yes | | robynn_website_audit_status | Website intelligence | Polls the prospect audit row/run created by robynn_website_audit until the designed audit page has report data and download artifacts | Yes | | robynn_website_strategy | Website intelligence | robynnv3 website adapter -> LangGraph website_report_v1 | Yes |

All tools return both content (text for LLM) and structuredContent (machine-readable JSON). Long-running robynn_create_content, robynn_research, and robynn_assist runs may return a pending run_id instead of blocking until completion; use robynn_run_status to fetch the final output. robynn_cmo_agent follows the same pending model through robynn_run_status, while robynn_campaign_creator may return a pending LangGraph thread/run pair that should be checked with robynn_campaign_status. The local CLI now waits only briefly for those runs before returning pending, which avoids MCP client timeouts in command-based agents like OpenClaw. You can tune that short wait with ROBYNN_MCP_SYNC_WAIT_MS (default 8000, max 30000). Tools with inline app support expose MCP Apps resources from the Worker, while the backend agent or service only returns data.

For Robynn-owned prospecting, robynn_website_audit creates the same public prospect audit page used by Super Admin and returns an unlisted audit_url, prospect_audit_id, and LangGraph thread/run IDs. Use robynn_website_audit_status with the returned prospect_audit_id to poll until the designed audit page is complete; completed status responses include pdf_url only when the underlying Super Admin PDF artifact exists. Completed robynn_campaign_creator / robynn_campaign_status responses persist canonical content as Rory/Brand Hub artifacts and include unlisted robynn.ai report_url links. These URLs are tokenized share links intended for prospecting handoff; raw Supabase Storage URLs are not returned.

Detailed execution mapping for every tool lives in docs/architecture/robynn-mcp-tool-execution-matrix.md.

OAuth Flow

1. Claude calls /register (Dynamic Client Registration) — gets a client_id
2. Claude redirects user to /authorize on the Worker
3. Worker redirects to robynn.ai/oauth/authorize (consent page)
4. User logs in via Supabase Auth, clicks "Allow"
5. Robynn generates auth code, redirects to Worker's /callback
6. Worker exchanges code for JWT access token via robynn.ai/api/oauth/token
7. Worker calls completeAuthorization() — OAuthProvider issues its own token to Claude
8. Claude makes tool calls to /mcp with Bearer token
9. McpAgent resolves token to user's props (robynn.ai access token)
10. Tools call robynn.ai API with the access token

Tech Stack

• Runtime: Cloudflare Workers (Durable Objects)
• MCP SDK: @modelcontextprotocol/sdk v1.26
• Agent Framework: agents (Cloudflare McpAgent)
• OAuth: @cloudflare/workers-oauth-provider
• Routing: Hono (for the auth handler)
• Language: TypeScript

Project Structure

src/
├── index.ts              # Worker entry: RobynnMCP (McpAgent DO) + OAuthProvider
├── auth-handler.ts       # Hono app: /authorize redirect, /callback token exchange
├── robynn-client.ts      # HTTP client for robynn.ai API (10s read, configurable poll timeout)
├── types.ts              # Env, Props, API response types
├── ui/                   # Shared Robynn MCP Apps report resources and runtime
└── tools/
    ├── context.ts        # robynn_brand_context + robynn_brand_context_search
    ├── status.ts         # robynn_status + robynn_usage
    ├── content.ts        # robynn_create_content
    ├── research.ts       # robynn_research
    ├── assist.ts         # robynn_assist
    ├── conversations.ts  # robynn_conversations
    ├── runs.ts           # robynn_run_status
    ├── cmo-agent.ts      # robynn_cmo_agent
    ├── campaign.ts       # robynn_campaign_creator + robynn_campaign_status
    ├── geo.ts            # robynn_geo_analysis
    ├── battlecard.ts     # robynn_competitive_battlecard
    ├── seo.ts            # robynn_seo_opportunities
    ├── brand-book.ts     # brand-book status, strategy, reflections, export tools
    └── website.ts        # website audit + website strategy tools

Development

pnpm install              # Install dependencies
npx wrangler dev          # Local dev server at http://localhost:8787
npx tsc --noEmit          # Type-check
npx wrangler deploy       # Deploy to Cloudflare

Local Testing

Detailed runbook: docs/local-testing.md

# Health check
curl http://localhost:8787/

# MCP config
curl http://localhost:8787/.well-known/mcp.json

# Test with MCP Inspector
npx @modelcontextprotocol/inspector
# Enter URL: http://localhost:8787/mcp

Connecting Claude Desktop (for testing)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "robynn": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.robynn.ai/sse"]
    }
  }
}

Connecting on claude.ai

Settings → Connectors → Add Custom Connector → https://mcp.robynn.ai

Deployment

# Type-check + deploy (2 commands)
npx tsc --noEmit
npx wrangler deploy

Changes are live at mcp.robynn.ai within seconds.

Environment

| Variable | Value | Set via | |----------|-------|---------| | ROBYNN_API_BASE_URL | https://robynn.ai | wrangler.toml [vars] | | MCP_SERVER_NAME | Robynn | wrangler.toml [vars] | | MCP_SERVER_VERSION | 0.1.5 | wrangler.toml [vars] | | OAUTH_KEY | KV namespace | wrangler.toml binding | | MCP_OBJECT | Durable Object | wrangler.toml binding |

Required Cloudflare Resources

• KV Namespace: OAUTH_KEY — stores OAuth state during auth flow
• Durable Object: RobynnMCP — hosts MCP server instances per authenticated user

Related Projects

• robynnv3 — SvelteKit frontend + API (robynn.ai)
• robynnv3_agents — Python LangGraph agent backend
• robynn-claude-cmo — Rory CLI (local MCP server for Claude Code)

@robynn-ai/cli (Local Usage)

In addition to the Cloudflare-hosted remote server for Claude Web, this repository builds the official @robynn-ai/cli which provides a local Stdio MCP bridge (for Claude Code, Cursor) and standalone headless commands.

Installation

@robynn-ai/cli is intended to be installed from npm once the package has been published.

# Install globally
npm install -g @robynn-ai/cli

# Verify installation
robynn -h

OpenClaw Behavior

For command-based MCP clients such as OpenClaw, robynn_create_content and robynn_research wait only briefly for completion and then return a pending run_id that should be checked with robynn_run_status. robynn_cmo_agent behaves the same way for direct CMO requests, while robynn_campaign_creator may return a pending LangGraph thread/run pair that should be checked with robynn_campaign_status. This is intentional so long-running one-pagers, campaign plans, and research jobs do not hit the client's MCP request timeout.

If your MCP host can tolerate a slightly longer inline wait, set:

export ROBYNN_MCP_SYNC_WAIT_MS=12000

The CLI caps this at 30000ms.

Authentication

The CLI uses the exact same rbo_... organization keys from your Robynn dashboard.

robynn init rbo_YOUR_KEY_HERE
robynn auth status

CMO and campaign flows

The direct CMO and campaign tools are available in both the remote connector and the local CLI bridge:

• robynn_cmo_agent for direct top-level CMO requests
• robynn_campaign_creator for campaign generation; completed runs include unlisted robynn.ai report URLs
• robynn_campaign_status for follow-up polling on pending campaign runs; completed polls include the same saved artifact and report URLs

Example asks:

• "Create a launch plan for Acme's new analytics product"
• "Generate a marketing campaign for Acme targeting VP Marketing"
• "Check the status of the campaign run and return the saved artifact"

Viewing and Using Commands

The CLI runs the exact same execution paths as the Cloudflare tools, but locally:

# List all available commands
robynn --help

# Generate a GEO Analysis (outputs rich terminal text)
robynn analyze geo -q "Lucid Software" -c "software"

# Generate an SEO Report (outputs JSON for agent parsing)
robynn analyze seo -u "https://lucid.co" --json

# Read current brand context
robynn brand context --json

Local MCP Server (Cursor / Claude Code)

You can plug the exact same tool suite into your local agents without setting up the remote Cloudflare worker:

For Claude Code:

claude mcp add robynn-local -- robynn mcp

For Cursor:

1. Open Cursor Settings > MCP
2. Add new MCP server
3. Name: Robynn Local
4. Type: command
5. Command: robynn mcp

OpenClaw Install

For remote Linux hosts running OpenClaw, the CLI can patch the local OpenClaw MCP config for you:

After @robynn-ai/cli has been published to npm:

npm install -g @robynn-ai/cli
robynn install openclaw
robynn init rbo_YOUR_KEY_HERE

If you are installing from this repository before package publish:

git clone https://github.com/robynnai/robynnv3-mcp-connector.git
cd robynnv3-mcp-connector
pnpm install
pnpm build:cli
node dist/robynn.cjs install openclaw
node dist/robynn.cjs init rbo_YOUR_KEY_HERE

What this does:

• robynn install openclaw looks for OpenClaw config in:
  • /home/$USER/.openclaw/openclaw.json
  • ~/.openclaw/openclaw.json
• If it finds a config file, it adds or updates:

{
  "mcp": {
    "servers": {
      "robynn": {
        "command": "robynn",
        "args": ["mcp"]
      }
    }
  }
}

• If it cannot find or safely patch the config, it prints exact manual instructions instead.
• robynn init rbo_... stores the org key in ~/.robynn/config.json, which is then used by robynn mcp.
• OpenClaw stores the saved local server entry under mcp.servers.robynn.

Publishing @robynn-ai/cli

The package metadata in this repository is set up for npm publication. Publishing still requires npm credentials on the machine that runs the release:

npm adduser
pnpm test
pnpm typecheck
pnpm build:cli
npm publish --access public

After publish completes, remote Linux hosts can install the CLI with npm install -g @robynn-ai/cli.

Connectors Directory Submission

Submit at anthropic.com/partners/mcp. Requirements:

• [x] OAuth 2.0 with Dynamic Client Registration
• [x] Safety annotations on all tools
• [x] Structured JSON responses
• [x] HTTPS/TLS (Cloudflare automatic)
• [x] .well-known/mcp.json discovery endpoint
• [x] Responses under 25,000 tokens
• [ ] Test account with sample brand data
• [ ] Privacy policy link
• [ ] Rate limiting on robynn.ai API