Opsee MCP Server

Manage your Opsee projects, tasks, docs, and cycles directly from AI-powered coding environments like Claude Code and Cursor.

Quick Start

1. Authenticate

npx @opsee/mcp-server login

This opens your browser to sign in to Opsee. Your credentials are saved to ~/.opsee/credentials.json.

2. Add to Claude Code

claude mcp add opsee -- npx @opsee/mcp-server serve

3. Restart Claude Code

Exit and reopen Claude Code. Run /mcp to verify opsee shows as connected.

4. Start using it

Ask Claude things like:

• "List my Opsee projects"
• "Show tasks in project Codlas"
• "Create a task called 'Fix login bug' in project 1"
• "What cycles are active in project 1?"
• "Show me the docs in project 1"

Available Tools (19)

| Tool | Description | |------|-------------| | opsee_get_me | Get your profile info | | opsee_list_projects | List all projects | | opsee_get_project | Get project details | | opsee_list_tasks | List tasks with filters | | opsee_get_task | Get task details | | opsee_create_task | Create a new task | | opsee_update_task | Update task fields | | opsee_list_task_types | Get task types (Bug, Feature, etc.) | | opsee_list_task_priorities | Get priority levels | | opsee_list_boards | List Kanban boards | | opsee_list_board_columns | Get board columns/statuses | | opsee_list_cycles | List cycles/sprints | | opsee_get_cycle | Get cycle details | | opsee_create_cycle | Create a new cycle | | opsee_list_doc_spaces | List doc spaces | | opsee_list_doc_pages | List pages in a doc space | | opsee_get_doc_page | Read a doc page | | opsee_create_doc_page | Create a new doc page | | opsee_list_repositories | List connected repositories |

Remote MCP Server (Recommended)

The remote server runs in the cloud with OAuth 2.0 authentication — no local setup or tokens needed.

Environments

| Environment | URL | Opsee Instance | |-------------|-----|----------------| | Production | https://mcp.api.opsee.ai/mcp | https://opsee.ai | | Development | https://opsee-development.mcp.cls.codilas.link/mcp | https://opsee-development.cdn.codilas.link |

Claude Code

# Production
claude mcp add opsee --transport http https://mcp.api.opsee.ai/mcp

# Development
claude mcp add opsee-dev --transport http https://opsee-development.mcp.cls.codilas.link/mcp

Restart Claude Code. On first use, your browser opens for Opsee login. After authenticating, all tools are available immediately.

You can have both environments connected at the same time — use tools prefixed with the server name (e.g. opsee for production, opsee-dev for development).

Cursor / Other MCP Clients

{
  "mcpServers": {
    "opsee": {
      "type": "http",
      "url": "https://mcp.api.opsee.ai/mcp"
    }
  }
}

Replace the URL with the development endpoint if targeting that environment.

Your MCP client handles the OAuth flow automatically — just sign in when prompted.

How it works

1. Client connects to the MCP endpoint (e.g. https://mcp.api.opsee.ai/mcp)
2. Server returns 401 with OAuth discovery metadata
3. Client registers itself and opens the Opsee login page in your browser
4. After login, the client exchanges the auth code for an access token
5. All subsequent tool calls use the token automatically

Local MCP Server (Alternative)

Run the MCP server locally via npx. Requires a one-time login to get a token.

1. Authenticate

npx @opsee/mcp-server login

2. Add to Claude Code

claude mcp add opsee -- npx @opsee/mcp-server serve

Cursor / Other MCP Clients (Local)

{
  "mcpServers": {
    "opsee": {
      "command": "npx",
      "args": ["@opsee/mcp-server", "serve"]
    }
  }
}

CI / Headless Environments

Skip the browser login by setting a token directly:

{
  "mcpServers": {
    "opsee": {
      "command": "npx",
      "args": ["@opsee/mcp-server", "serve"],
      "env": {
        "OPSEE_API_TOKEN": "your-jwt-token"
      }
    }
  }
}

Self-Hosting the Remote Server

Deploy the MCP server in your own infrastructure using Docker.

Docker

docker build -f mcp/Dockerfile . -t opsee-mcp-server

docker run -p 3100:3100 \
  -e MCP_SERVER_URL=https://mcp.yourdomain.com \
  -e OPSEE_API_URL=http://your-backend:8080 \
  -e OPSEE_APP_URL=https://your-frontend.com \
  opsee-mcp-server

Kubernetes

The server includes Kustomize configs following the same pattern as the backend:

# Development
kubectl apply -k mcp/k8/environments/development/ -n opsee-development

# Production
kubectl apply -k mcp/k8/environments/production/ -n opsee-production

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MCP_SERVER_URL | Public URL of this MCP server (for OAuth redirects) | http://localhost:3100 | | MCP_HOST | Bind host | 0.0.0.0 | | MCP_PORT | Bind port | 3100 | | OPSEE_API_URL | Backend Connect RPC URL | https://grpc.api.opsee.ai | | OPSEE_APP_URL | Frontend URL (OAuth login page) | https://opsee.ai | | OPSEE_API_TOKEN | Direct JWT token for local mode | — | | OPSEE_CREDENTIALS_PATH | Override credential file path | ~/.opsee/credentials.json |

Local Development

# Start backend + frontend locally, then:

# Local mode (stdio):
OPSEE_APP_URL=http://localhost:5173 OPSEE_API_URL=http://localhost:9990 npx @opsee/mcp-server login
claude mcp add opsee -e OPSEE_API_URL=http://localhost:9990 -- npx @opsee/mcp-server serve

# Remote mode (HTTP):
MCP_SERVER_URL=http://localhost:3100 OPSEE_API_URL=http://localhost:9990 OPSEE_APP_URL=http://localhost:5173 npx @opsee/mcp-server serve-remote
claude mcp add opsee-local --transport http http://localhost:3100/mcp