Code Ocean MCP Server

Model Context Protocol (MCP) server for Code Ocean.

This MCP server provides tools to search, run, and release capsules and pipelines, and manage data assets.

Table of Contents

• Prerequisites
• Code Ocean Platform Version Compatibility
• Installation
  • Visual Studio Code
  • Claude Desktop
  • Cline
  • Roo Code
  • Cursor
  • Windsurf
• Streamable HTTP Transport
• Local Testing

Prerequisites

1. Install uv from Astral or the GitHub README
2. Install Python 3.10 or newer using uv python install 3.10 (or a more recent version)
3. Generate a Code Ocean access token. Follow instructions in the Code Ocean user guide.

Code Ocean Platform Version Compatibility

Each release of this Code Ocean MCP Server is tested and verified against a specific minimum version of the Code Ocean platform API. Generally, this minimum version is the latest Code Ocean version at the time of the MCP Server release. We recommend ensuring your MCP Server dependency is pinned to a version compatible with your Code Ocean deployment. For details on when the minimum Code Ocean platform version changes, see the CHANGELOG.

Installation

Visual Studio Code

Here's an example VS Code MCP server configuration:

{
    ...
    "mcp": {
        "inputs": [
            {
            "type": "promptString",
            "id": "codeocean-token",
            "description": "Code Ocean API Key", 
            "password": true
            }
        ],
        "servers": {
            "codeocean": {
                "type": "stdio",
                "command": "uvx",
                "args": ["codeocean-mcp-server"],
                "env": {
                    "CODEOCEAN_DOMAIN": "https://codeocean.acme.com",
                    "CODEOCEAN_TOKEN": "${input:codeocean-token}",
                    "AGENT_ID": "VS Code"
                }
            }
        },
    }
}

Claude Desktop

1. Open the claude_desktop_config.json file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

1. Under the top-level "mcpServers" object, add a "codeocean" entry. For a stdio transport (child-process) it looks like this:

{
  "mcpServers": {
    "codeocean": {
      "command": "uvx",
      "args": ["codeocean-mcp-server"],
      "env": {
        "CODEOCEAN_DOMAIN": "https://codeocean.acme.com",
        "CODEOCEAN_TOKEN": "<YOUR_API_KEY>",
        "AGENT_ID": "Claude Desktop"
      }
    }
  }
}

Cline

Cline stores all of its MCP settings in a JSON file called cline_mcp_settings.json. You can edit this either through the GUI (“Configure MCP Servers” in the MCP Servers pane) or by hand:

1. Open Cline and click the MCP Servers icon in the sidebar.
2. In the “Installed” tab, click Configure MCP Servers → this opens your cline_mcp_settings.json.
3. Add a "codeocean" server under the "mcpServers" key. For stdio transport:

{
  "mcpServers": {
    "codeocean": {
      "command": "uvx",
      "args": ["codeocean-mcp-server"],
      "env": {
        "CODEOCEAN_DOMAIN": "https://codeocean.acme.com",
        "CODEOCEAN_TOKEN": "<YOUR_API_KEY>",
        "AGENT_ID": "Cline"
      },
      "alwaysAllow": [],       // optional: list of tools to auto-approve
      "disabled": false        // ensure it’s enabled
    }
  }
}

1. Save the file. Cline will automatically detect and launch the new server, making your Code Ocean tools available in chat .

Roo Code

Roo Code’s MCP support is configured globally across all workspaces via a JSON settings file or through its dedicated MCP Settings UI

Via the MCP Settings UI:

1. Click the MCP icon in Roo Code’s sidebar. 
2. Select Edit MCP Settings (opens cline_mcp_settings.json). 
3. Under "mcpServers", add:

{
  "mcpServers": {
    "codeocean": {
      "command": "uvx",
      "args": ["codeocean-mcp-server"],
      "env": {
        "CODEOCEAN_DOMAIN": "https://codeocean.acme.com",
        "CODEOCEAN_TOKEN": "<YOUR_API_KEY>",
        "AGENT_ID": "Roo Code"
      }
    }
  }
}

1. Save and restart Roo Code; your Code Ocean tools will appear automatically.

Optional: Manually editing cline_mcp_settings.json

1. Locate cline_mcp_settings.json (in your home directory or workspace). 
2. Insert the same "codeocean" block under "mcpServers" as above.
3. Save and restart.

Cursor

Cursor stores MCP servers in a JSON file at either ~/.cursor/mcp.json (global) or {project}/.cursor/mcp.json (project-specific) .

1. Open .cursor/mcp.json (or create it if missing). 
2. Add under "mcpServers":

{
  "mcpServers": {
    "codeocean": {
      "command": "uvx",
      "args": ["codeocean-mcp-server"],
      "env": {
        "CODEOCEAN_DOMAIN": "https://codeocean.acme.com",
        "CODEOCEAN_TOKEN": "<YOUR_API_KEY>",
        "AGENT_ID": "Cursor"
      }
    }
  }
}

1. Save the file. Cursor will automatically detect and launch the new server on next start. 

Windsurf

Windsurf (Cascade) uses mcp_config.json under ~/.codeium/windsurf/ (or via the Cascade → MCP Servers UI) .

1. Open your Windsurf Settings and navigate to Cascade → MCP Servers, then click View Raw Config to open mcp_config.json. 
2. Insert the following under "mcpServers":

{
  "mcpServers": {
    "codeocean": {
      "command": "uvx",
      "args": ["codeocean-mcp-server"],
      "env": {
        "CODEOCEAN_DOMAIN": "https://codeocean.acme.com",
        "CODEOCEAN_TOKEN": "<YOUR_API_KEY>",
        "AGENT_ID": "Windsurf"
      }
    }
  }
}

1. Save and restart Windsurf (or hit “Refresh” in the MCP panel).

Streamable HTTP Transport

By default the server runs over stdio and authenticates with the CODEOCEAN_TOKEN environment variable, as described above. It can also serve multiple users from a single process over streamable HTTP, taking each caller's API token from the request instead:

CODEOCEAN_DOMAIN=https://acmecorp.codeocean.com codeocean-mcp-server --transport streamable-http --host 127.0.0.1 --port 8000

Clients then pass their own token as Authorization: Bearer <YOUR_API_KEY> on every request; CODEOCEAN_TOKEN is not used, and a request without a token is refused. The endpoint is http://<host>:<port>/mcp.

Local Testing

You can test the MCP server locally during development with MCP Inspector:

npx @modelcontextprotocol/inspector uv tool run codeocean-mcp-server

This will start a web server where you can:

• View available tools and resources
• Test tool calls interactively
• See server logs and responses

Log Formatting (Optional)

The MCP server supports custom log formatting through the LOG_FORMAT environment variable. This allows you to control the format of log messages output by the server. Example Format Strings: "%(asctime)s %(levelname)s [%(name)s] %(message)s". If LOG_FORMAT is not set, the server uses FastMCP's default logging configuration.

The LOG_LEVEL environment variable sets the level the server logs at: DEBUG, INFO (the default), WARNING, ERROR or CRITICAL. Raising it drops the record the server writes for every request it serves, which is worth doing when the server runs alongside a caller that logs those requests itself.