Perdoo MCP Server

An MCP (Model Context Protocol) server that integrates with the Perdoo OKR platform via its GraphQL API. Provides 19 tools for managing objectives, key results, initiatives, KPIs, and strategic pillars.

Features

• Full CRUD for objectives, key results, initiatives, KPIs, and strategic pillars
• Helper tools for looking up timeframes, users, and groups
• Cursor-based pagination on all list operations
• Resilience stack: rate limiting, circuit breaker, retry with exponential backoff, request queuing
• Session-based HTTP transport (Streamable HTTP)
• Instructions resource at perdoo://instructions for LLM guidance

Tools

Category	Tools
Objectives	list_objectives, get_objective, create_objective, update_objective
Key Results	list_key_results, get_key_result, create_key_result, update_key_result
Initiatives	list_initiatives, get_initiative, create_initiative, update_initiative
KPIs	list_kpis, get_kpi, create_kpi, update_kpi
Strategic Pillars	list_strategic_pillars, get_strategic_pillar
Helpers	list_timeframes, list_users, list_groups

Setup

Prerequisites

• Node.js >= 18
• A Perdoo API token (generate one in Perdoo settings)

Install and run

git clone https://github.com/nevilhulspas/perdoo-mcp.git
cd perdoo-mcp
npm install
cp .env.example .env
# Edit .env and add your PERDOO_API_TOKEN
npm run build
npm start

The server starts on port 3001 by default.

Development

npm run dev  # Watch mode with tsx

Docker

npm run docker:build
npm run docker:run

Configuration

Variable	Required	Default	Description
PERDOO_API_TOKEN	Yes	-	Bearer token for the Perdoo GraphQL API
PORT	No	3001	HTTP server port
NODE_ENV	No	development	Environment (development or production)

MCP Client Configuration

Local

{
  "mcpServers": {
    "perdoo": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

Remote

When deployed to a remote server with a domain:

{
  "mcpServers": {
    "perdoo": {
      "url": "https://perdoo-mcp.yourdomain.com/mcp"
    }
  }
}

Remote Deployment (Dokploy)

This server is designed to run remotely via its HTTP transport. The included Dockerfile makes it straightforward to deploy on any container platform. Below are instructions for Dokploy on a VPS (e.g. Hetzner).

1. Create the application

In your Dokploy dashboard:

1. Create a new Application
2. Set source to Git and point it to this repo (https://github.com/nevilhulspas/perdoo-mcp.git)
3. Set build type to Dockerfile (it will auto-detect the Dockerfile in the repo root)

2. Configure environment variables

In the application's Environment tab, add:

PERDOO_API_TOKEN=your-bearer-token-here
PORT=3001
NODE_ENV=production

3. Configure the domain

In the Domains tab:

1. Add your domain (e.g. perdoo-mcp.yourdomain.com)
2. Enable HTTPS (Dokploy handles Let's Encrypt automatically via Traefik)
3. Set the container port to 3001

4. Health check

Configure the health check in Dokploy to use:

• Path: /health
• Port: 3001
• Expected status: 200

5. Deploy

Click Deploy. Dokploy will build the Docker image and start the container.

Security considerations

The MCP endpoint has no built-in authentication. Anyone who can reach your server can use the Perdoo tools with your API token.

For production deployments, secure the endpoint using one of these approaches:

• Traefik BasicAuth middleware - Add basic auth via Dokploy's Traefik config labels
• API key middleware - Add a custom Express middleware that checks an Authorization header (see Auth section below)
• IP allowlisting - Restrict access to known IPs via firewall rules or Traefik's ipAllowList middleware
• VPN/Tailscale - Run the server on a private network only accessible via VPN

Session persistence

Sessions are stored in-memory. A container restart (deploy, crash, scaling) drops all active MCP sessions. Clients will need to re-initialize. This is expected behavior for MCP's Streamable HTTP transport.

Resource sizing

The server is lightweight (single-concurrency request queue, no database). A minimal VPS (1 vCPU, 512 MB RAM) is sufficient.

Endpoints

Method	Path	Description
POST	/mcp	MCP request handler (creates sessions on initialize)
GET	/mcp	SSE endpoint for server notifications
DELETE	/mcp	Session termination
GET	/health	Health check (status, version, active sessions)

Architecture

src/
├── server.ts                    # Express HTTP server with session management
├── lib/
│   ├── env.ts                   # Environment validation (Zod)
│   ├── errors.ts                # Typed error classes
│   └── logger.ts                # Structured logging
├── mcp/
│   ├── index.ts                 # MCP server factory
│   └── tools/                   # Tool definitions (one file per entity)
└── services/perdoo/
    ├── client.ts                # GraphQL client with resilience stack
    ├── types.ts                 # TypeScript types and enums
    ├── operations/              # GraphQL queries and mutations
    ├── circuit-breaker.ts       # Fails-open after 5 failures
    ├── rate-limiter.ts          # Token bucket (30 capacity, 3/sec)
    ├── request-queue.ts         # Single concurrent request
    └── retry.ts                 # Exponential backoff (queries only)

Resilience

The client applies a resilience stack in order:

1. Request Queue - Ensures only one request at a time
2. Circuit Breaker - Opens after 5 consecutive failures, resets after 30s
3. Retry - Exponential backoff for queries only (mutations are never retried)
4. Rate Limiter - Token bucket with 30 capacity, refilling at 3 tokens/sec

Adding Authentication

The server does not include authentication out of the box. For production use, add a shared-secret middleware:

1. Add a MCP_API_KEY environment variable
2. Add middleware to src/server.ts that checks the Authorization: Bearer <key> header on /mcp routes
3. Configure your MCP client to send the header:

{
  "mcpServers": {
    "perdoo": {
      "url": "https://perdoo-mcp.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer your-mcp-api-key"
      }
    }
  }
}

Alternatively, use Traefik's built-in BasicAuth middleware at the reverse proxy level (no code changes required).

License

MIT