Connect the Corvos MCP server to Claude Code, Codex, OpenCode, Cursor, and other MCP clients, step by step

Corvos MCP Server

The Corvos MCP server exposes your workspace to any Model Context Protocol client. Your agent gets 28 native, typed tools: every scraper (Reddit, YouTube, Instagram, TikTok, Google Maps, Google Search, Indeed, Amazon, Walmart, web crawl), full knowledge-base access (search, read, add, upload, update, delete), and a workspace selector.

Connect it two ways: the hosted server at https://mcp.corvos.com/mcp (nothing to install - just an API key), or run it yourself over stdio against any Corvos backend, cloud or self-hosted.

Create an API key

You need a Corvos API key either way. In Corvos, open API Playground → API Keys in your workspace sidebar:

Toggle API key access on for the workspace.
Create a personal API key (ss_pat_…) and copy it - it is shown only once.

Connect (hosted)

The hosted server runs at https://mcp.corvos.com/mcp. Point your client at it and send the key as a Bearer token - there is nothing to install and no backend to run. For clients that read an mcpServers map (Cursor, and others):

{
  "mcpServers": {
    "corvos": {
      "url": "https://mcp.corvos.com/mcp",
      "headers": { "Authorization": "Bearer ss_pat_your_key_here" }
    }
  }
}

Claude Code, from a terminal:

claude mcp add --transport http corvos https://mcp.corvos.com/mcp \
  --header "Authorization: Bearer ss_pat_your_key_here"

Most MCP clients accept this url + headers form; check your client's docs for its exact remote-server field.

Self-host (stdio)

Run the server yourself when you host your own backend or use a client without remote support. It runs with uv - install it once, then from the Corvos repository run:

cd mcp
uv sync

Point the server at your backend with CORVOS_BASE_URL:

Corvos Cloud: https://api.corvos.com
Self-hosted: wherever your backend runs, e.g. http://localhost:8000

Every client below launches the same command - uv run --directory <path-to>/mcp python -m mcp_server - and passes CORVOS_BASE_URL and CORVOS_API_KEY as environment variables. Replace the placeholder paths and key with yours.

Run one command in a terminal:

claude mcp add corvos \
  -e CORVOS_BASE_URL=https://api.corvos.com \
  -e CORVOS_API_KEY=ss_pat_your_key_here \
  -- uv run --directory /path/to/Corvos/mcp python -m mcp_server

Start Claude Code and run /mcp - corvos should be listed as connected. Add --scope project to share the server (without the key) via a checked-in .mcp.json.

Add to ~/.codex/config.toml (or a project's .codex/config.toml):

[mcp_servers.corvos]
command = "uv"
args = ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"]

[mcp_servers.corvos.env]
CORVOS_BASE_URL = "https://api.corvos.com"
CORVOS_API_KEY = "ss_pat_your_key_here"

Or use the CLI: codex mcp add corvos -e CORVOS_API_KEY=... -- uv run --directory ... python -m mcp_server. Verify with codex mcp list.

Add to opencode.json in your project root (or ~/.config/opencode/opencode.json globally):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "corvos": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "enabled": true,
      "environment": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

OpenCode's format differs from most clients: the root key is mcp (not mcpServers), the command is a single array, and environment variables go under environment (not env).

Add to ~/.cursor/mcp.json (global - keeps the key out of your repo) or a project's .cursor/mcp.json:

{
  "mcpServers": {
    "corvos": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "env": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

Then open Cursor Settings → MCP and refresh the corvos server; its 25 tools should appear with a green dot.

Open Settings → Developer → Edit Config to reach claude_desktop_config.json, and add the same mcpServers block as Cursor:

{
  "mcpServers": {
    "corvos": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "env": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

Restart Claude Desktop; Corvos appears under the tools icon in the chat input.

Add to .vscode/mcp.json in your workspace (or run the MCP: Add Server command). Note VS Code uses a servers key:

{
  "servers": {
    "corvos": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "env": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

Open Copilot Chat in agent mode and click the tools icon to confirm the server is loaded.

Add the standard mcpServers block to ~/.codeium/windsurf/mcp_config.json (or via Windsurf Settings → Cascade → MCP Servers):

{
  "mcpServers": {
    "corvos": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "env": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

Press refresh in the MCP panel to pick up the server.

Add the standard mcpServers block to ~/.gemini/settings.json (or .gemini/settings.json in a project):

{
  "mcpServers": {
    "corvos": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "env": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

Run /mcp inside Gemini CLI to confirm the server and its tools.

stdio transport - nothing to keep running

In this mode your client launches the process on demand and shuts it down with the session. There is no daemon to manage - only your Corvos backend needs to be up. (The hosted server above needs none of this.)

Test it

In a fresh agent session, try:

list my Corvos workspaces

That calls corvos_list_workspaces - the simplest end-to-end check of the key, backend, and server. Then try a real task:

find the top subreddits discussing NotebookLM and save a summary note to my workspace

Configuration reference

For self-host (stdio), all settings are environment variables passed by the client. The hosted server needs only your API key in the Authorization header:

Variable	Required	Default	Purpose
`CORVOS_API_KEY`	Yes	-	API key from API Playground → API Keys
`CORVOS_BASE_URL`	No	`http://localhost:8000`	Backend to talk to
`CORVOS_WORKSPACE`	No	-	Default workspace by name or id, so agents skip selection
`CORVOS_TIMEOUT`	No	`180`	Request timeout in seconds

Troubleshooting

401 errors - the API key is wrong or expired; create a new one.
403 errors - API access is disabled for the workspace; toggle API key access on under API Playground → API Keys.
"Could not reach Corvos" - the backend isn't running or CORVOS_BASE_URL is wrong.
Server won't start - run uv run python -m mcp_server.selfcheck inside mcp; it verifies all 25 tools register without needing a backend.

Tools reference

Group	Tools
Workspaces	`corvos_list_workspaces`, `corvos_select_workspace`
Scrapers	`corvos_reddit_scrape`, `corvos_youtube_scrape`, `corvos_youtube_comments`, `corvos_instagram_scrape`, `corvos_instagram_details`, `corvos_tiktok_scrape`, `corvos_tiktok_comments`, `corvos_tiktok_user_search`, `corvos_tiktok_trending`, `corvos_google_maps_scrape`, `corvos_google_maps_reviews`, `corvos_google_search`, `corvos_indeed_scrape`, `web_crawl`, `corvos_list_scraper_runs`, `corvos_get_scraper_run`
Knowledge base	`corvos_search_knowledge_base`, `corvos_list_documents`, `corvos_get_document`, `corvos_add_document`, `corvos_upload_file`, `corvos_update_document`, `corvos_delete_document`

Usage is billed exactly like the REST API - scraper tools are metered per returned item, and every call is recorded under API Playground → Runs.

Corvos MCP Server

Connect it two ways: the hosted server at https://mcp.corvos.com/mcp (nothing to install - just an API key), or run it yourself over stdio against any Corvos backend, cloud or self-hosted.

Create an API key

You need a Corvos API key either way. In Corvos, open API Playground → API Keys in your workspace sidebar:

Toggle API key access on for the workspace.
Create a personal API key (ss_pat_…) and copy it - it is shown only once.

Connect (hosted)

{
  "mcpServers": {
    "corvos": {
      "url": "https://mcp.corvos.com/mcp",
      "headers": { "Authorization": "Bearer ss_pat_your_key_here" }
    }
  }
}

Claude Code, from a terminal:

claude mcp add --transport http corvos https://mcp.corvos.com/mcp \
  --header "Authorization: Bearer ss_pat_your_key_here"

Most MCP clients accept this url + headers form; check your client's docs for its exact remote-server field.

Self-host (stdio)

Run the server yourself when you host your own backend or use a client without remote support. It runs with uv - install it once, then from the Corvos repository run:

cd mcp
uv sync

Point the server at your backend with CORVOS_BASE_URL:

Corvos Cloud: https://api.corvos.com
Self-hosted: wherever your backend runs, e.g. http://localhost:8000

Run one command in a terminal:

claude mcp add corvos \
  -e CORVOS_BASE_URL=https://api.corvos.com \
  -e CORVOS_API_KEY=ss_pat_your_key_here \
  -- uv run --directory /path/to/Corvos/mcp python -m mcp_server

Start Claude Code and run /mcp - corvos should be listed as connected. Add --scope project to share the server (without the key) via a checked-in .mcp.json.

Add to ~/.codex/config.toml (or a project's .codex/config.toml):

[mcp_servers.corvos]
command = "uv"
args = ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"]

[mcp_servers.corvos.env]
CORVOS_BASE_URL = "https://api.corvos.com"
CORVOS_API_KEY = "ss_pat_your_key_here"

Or use the CLI: codex mcp add corvos -e CORVOS_API_KEY=... -- uv run --directory ... python -m mcp_server. Verify with codex mcp list.

Add to opencode.json in your project root (or ~/.config/opencode/opencode.json globally):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "corvos": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "enabled": true,
      "environment": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

OpenCode's format differs from most clients: the root key is mcp (not mcpServers), the command is a single array, and environment variables go under environment (not env).

Add to ~/.cursor/mcp.json (global - keeps the key out of your repo) or a project's .cursor/mcp.json:

{
  "mcpServers": {
    "corvos": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "env": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

Then open Cursor Settings → MCP and refresh the corvos server; its 25 tools should appear with a green dot.

Open Settings → Developer → Edit Config to reach claude_desktop_config.json, and add the same mcpServers block as Cursor:

{
  "mcpServers": {
    "corvos": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "env": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

Restart Claude Desktop; Corvos appears under the tools icon in the chat input.

Add to .vscode/mcp.json in your workspace (or run the MCP: Add Server command). Note VS Code uses a servers key:

{
  "servers": {
    "corvos": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "env": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

Open Copilot Chat in agent mode and click the tools icon to confirm the server is loaded.

Add the standard mcpServers block to ~/.codeium/windsurf/mcp_config.json (or via Windsurf Settings → Cascade → MCP Servers):

{
  "mcpServers": {
    "corvos": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "env": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

Press refresh in the MCP panel to pick up the server.

Add the standard mcpServers block to ~/.gemini/settings.json (or .gemini/settings.json in a project):

{
  "mcpServers": {
    "corvos": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Corvos/mcp", "python", "-m", "mcp_server"],
      "env": {
        "CORVOS_BASE_URL": "https://api.corvos.com",
        "CORVOS_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

Run /mcp inside Gemini CLI to confirm the server and its tools.

stdio transport - nothing to keep running

Test it

In a fresh agent session, try:

list my Corvos workspaces

That calls corvos_list_workspaces - the simplest end-to-end check of the key, backend, and server. Then try a real task:

find the top subreddits discussing NotebookLM and save a summary note to my workspace

Configuration reference

For self-host (stdio), all settings are environment variables passed by the client. The hosted server needs only your API key in the Authorization header:

Variable	Required	Default	Purpose
`CORVOS_API_KEY`	Yes	-	API key from API Playground → API Keys
`CORVOS_BASE_URL`	No	`http://localhost:8000`	Backend to talk to
`CORVOS_WORKSPACE`	No	-	Default workspace by name or id, so agents skip selection
`CORVOS_TIMEOUT`	No	`180`	Request timeout in seconds

Troubleshooting

401 errors - the API key is wrong or expired; create a new one.
403 errors - API access is disabled for the workspace; toggle API key access on under API Playground → API Keys.
"Could not reach Corvos" - the backend isn't running or CORVOS_BASE_URL is wrong.
Server won't start - run uv run python -m mcp_server.selfcheck inside mcp; it verifies all 25 tools register without needing a backend.

Tools reference

Group	Tools
Workspaces	`corvos_list_workspaces`, `corvos_select_workspace`
Scrapers	`corvos_reddit_scrape`, `corvos_youtube_scrape`, `corvos_youtube_comments`, `corvos_instagram_scrape`, `corvos_instagram_details`, `corvos_tiktok_scrape`, `corvos_tiktok_comments`, `corvos_tiktok_user_search`, `corvos_tiktok_trending`, `corvos_google_maps_scrape`, `corvos_google_maps_reviews`, `corvos_google_search`, `corvos_indeed_scrape`, `web_crawl`, `corvos_list_scraper_runs`, `corvos_get_scraper_run`
Knowledge base	`corvos_search_knowledge_base`, `corvos_list_documents`, `corvos_get_document`, `corvos_add_document`, `corvos_upload_file`, `corvos_update_document`, `corvos_delete_document`

Usage is billed exactly like the REST API - scraper tools are metered per returned item, and every call is recorded under API Playground → Runs.

MCP Server

Corvos MCP Server

Create an API key

Connect (hosted)

Self-host (stdio)

Test it

Configuration reference

Troubleshooting

Tools reference

On this page

MCP Server

Corvos MCP Server

Create an API key

Connect (hosted)

Self-host (stdio)

Test it

Configuration reference

Troubleshooting

Tools reference

On this page