npm package: @strait/mcp-server
Description: MCP server for Strait — lets any AI agent manage job orchestration natively
Latest version: 0.1.5

<p align="center">
  <img src="github.png" alt="Strait" width="100%" />
</p>

<p align="center">
  <strong>MCP Server for the Strait Platform</strong>
</p>

<p align="center">
  <a href="https://github.com/strait-dev/mcp/actions/workflows/ci.yml"><img src="https://github.com/strait-dev/mcp/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://www.npmjs.com/package/@strait/mcp-server"><img src="https://img.shields.io/npm/v/@strait/mcp-server" alt="npm" /></a>
  <a href="https://www.npmjs.com/package/@strait/mcp-server"><img src="https://img.shields.io/node/v/@strait/mcp-server" alt="Node" /></a>
  <a href="https://github.com/strait-dev/mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License" /></a>
  <img src="https://img.shields.io/badge/types-strict-blue" alt="Types" />
  <img src="https://img.shields.io/badge/effect--ts-v3-purple" alt="Effect" />
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-brightgreen" alt="MCP" /></a>
  <a href="https://github.com/strait-dev/mcp/pkgs/container/mcp"><img src="https://img.shields.io/badge/docker-ghcr.io-blue" alt="Docker" /></a>
</p>

---

The official MCP server for [Strait](https://strait.dev) -- an open-source job execution and workflow orchestration platform for humans and AI agents. Lets any MCP-compatible client (Claude Desktop, Cursor, Windsurf, or custom agents) manage the complete Strait platform natively.

133 tools, 5 resources, 9 prompts. Full API coverage. Built with Effect TS for typed errors, structured concurrency, and dependency injection.

[Website](https://strait.dev) | [Platform Repo](https://github.com/strait-dev/strait) | [Documentation](https://docs.strait.dev) | [npm](https://www.npmjs.com/package/@strait/mcp-server)

## Installation

**npm** (recommended)

```bash
npm install -g @strait/mcp-server
```

**npx** (no install required)

```bash
npx @strait/mcp-server
```

**Docker**

```bash
docker pull ghcr.io/strait-dev/mcp
```

Requires Node.js 20+ for npm/npx.

## Quick Start

Set your API key:

```bash
export STRAIT_API_KEY=strait_live_...
```

Run in stdio mode (for IDE integrations):

```bash
npx @strait/mcp-server
```

Run in HTTP mode (for remote/production use):

```bash
npx @strait/mcp-server --transport http --port 3000
```

## Client Setup

### Claude Desktop

Add to your Claude Desktop config file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "strait": {
      "command": "npx",
      "args": ["@strait/mcp-server"],
      "env": {
        "STRAIT_API_KEY": "strait_live_..."
      }
    }
  }
}
```

Restart Claude Desktop after saving. The Strait tools will appear in the tools panel.

### Claude Code

Add via CLI (recommended):

```bash
claude mcp add strait --scope user -- npx @strait/mcp-server
```

Or add to `~/.claude.json` manually:

```json
{
  "mcpServers": {
    "strait": {
      "command": "npx",
      "args": ["@strait/mcp-server"],
      "env": {
        "STRAIT_API_KEY": "strait_live_..."
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project root (project-level) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "strait": {
      "command": "npx",
      "args": ["@strait/mcp-server"],
      "env": {
        "STRAIT_API_KEY": "strait_live_..."
      }
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "strait": {
      "command": "npx",
      "args": ["@strait/mcp-server"],
      "env": {
        "STRAIT_API_KEY": "strait_live_..."
      }
    }
  }
}
```

### OpenAI Codex CLI

Add via CLI:

```bash
codex mcp add strait -- npx @strait/mcp-server
```

Or add to `~/.codex/config.toml`:

```toml
[mcp_servers.strait]
type = "stdio"
command = "npx"
args = ["@strait/mcp-server"]

[mcp_servers.strait.env]
STRAIT_API_KEY = "strait_live_..."
```

### VS Code + GitHub Copilot

Open Settings (Ctrl+Shift+P > "MCP: Add Server") or add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "strait": {
      "command": "npx",
      "args": ["@strait/mcp-server"],
      "env": {
        "STRAIT_API_KEY": "strait_live_..."
      }
    }
  }
}
```

### Zed

Add to Zed settings (Zed > Settings > Open Settings):

```json
{
  "context_servers": {
    "strait": {
      "command": {
        "path": "npx",
        "args": ["@strait/mcp-server"],
        "env": {
          "STRAIT_API_KEY": "strait_live_..."
        }
      }
    }
  }
}
```

### Continue.dev

Add to `~/.continue/config.yaml`:

```yaml
mcpServers:
  - name: strait
    command: npx
    args: ["@strait/mcp-server"]
    env:
      STRAIT_API_KEY: strait_live_...
```

### Cline

Click the MCP Servers icon in Cline's toolbar, then "Edit MCP Settings" and add:

```json
{
  "mcpServers": {
    "strait": {
      "command": "npx",
      "args": ["@strait/mcp-server"],
      "env": {
        "STRAIT_API_KEY": "strait_live_..."
      }
    }
  }
}
```

### Amazon Q Developer

In VS Code or JetBrains, open Amazon Q settings and add an MCP server with:
- **Command**: `npx`
- **Args**: `@strait/mcp-server`
- **Environment**: `STRAIT_API_KEY=strait_live_...`

### JetBrains IDEs

Go to Settings > Tools > AI Assistant > MCP Servers, click "+" and add:
- **Command**: `npx`
- **Args**: `@strait/mcp-server`
- **Environment**: `STRAIT_API_KEY=strait_live_...`

### OpenCode

Add via CLI:

```bash
opencode mcp add strait -- npx @strait/mcp-server
```

Or add to your OpenCode config:

```yaml
mcp:
  strait:
    type: local
    command: npx
    args: ["@strait/mcp-server"]
    env:
      STRAIT_API_KEY: strait_live_...
```

### Docker

For remote or production deployments using HTTP transport:

```bash
docker run -e STRAIT_API_KEY=strait_live_... -p 3000:3000 ghcr.io/strait-dev/mcp
```

Or with Docker Compose:

```yaml
services:
  strait-mcp:
    image: ghcr.io/strait-dev/mcp
    ports:
      - "3000:3000"
    environment:
      STRAIT_API_KEY: ${STRAIT_API_KEY}
```

## What You Can Do

Once connected, ask your AI client to interact with Strait:

**Jobs** -- "List my jobs", "Create a job called data-sync that hits https://api.example.com/sync every hour", "Trigger the etl-pipeline job with this payload", "Show version history for my deploy job"

**Runs** -- "Show logs for the last failed run", "Why did run run_abc123 fail?", "Watch this run until it finishes", "Compare the last two runs of my sync job"

**Workflows** -- "Visualize the DAG for my nightly-batch workflow", "Create a workflow with three steps and an approval gate", "Trigger the onboarding pipeline"

**Deployments** -- "Validate this config before deploying", "Show what would change if I deploy", "Roll back the last deployment"

**Diagnostics** -- "What is the overall health of my project?", "Debug why run run_abc123 failed", "Suggest cost optimizations for my etl job"

**Analytics** -- "Show me cost trends for the last 30 days", "What are my top failing jobs?", "Show job reliability metrics"

**Infrastructure** -- "List my webhook subscriptions", "Create a notification channel for Slack", "Show my environments"

**Security** -- "List my API keys", "Rotate the deploy key with a 24-hour grace window", "List my secrets"

## Configuration

| Option | Env Var | CLI Flag | Default |
|--------|---------|----------|---------|
| API Key | `STRAIT_API_KEY` | `--api-key` | (required*) |
| Base URL | `STRAIT_BASE_URL` | `--base-url` | `https://api.strait.dev` |
| Transport | - | `--transport` | `stdio` |
| HTTP Port | - | `--port` | `3000` |
| OAuth Issuer | `OAUTH_ISSUER_URL` | - | (disabled) |
| OAuth Resource | `OAUTH_RESOURCE_URL` | - | (disabled) |

*API key is optional when OAuth is configured for HTTP transport. Set `OAUTH_ISSUER_URL` and `OAUTH_RESOURCE_URL` to enable OAuth -- users authenticate via browser instead of API key.

## Features

### Tools (133)

All operations return AI-optimized summaries with temporal context, resource IDs, and next-step hints.

| Category | Count | Examples |
|----------|-------|---------|
| **Jobs** | 15 | list, get, create, update, delete, trigger, bulk trigger, versions, clone, health, batch create/enable/disable, dependencies |
| **Runs** | 19 | list, get, logs, events, cancel, retry, watch, last run, diff, DLQ, bulk replay, children, outputs, usage, tool calls, pause, resume, reschedule |
| **Workflows** | 15 | list, get, create, update, delete, trigger, visualize DAG, graph, clone, dry-run, plan, simulate, versions, version diff |
| **Workflow Runs** | 15 | list, get, cancel, steps, watch, approve, reject, graph, timeline, resume, retry, force-complete step, retry step, bulk cancel, explain |
| **Event Triggers** | 3 | list, get, send event |
| **Secrets** | 3 | list (names only), create, delete |
| **Deployments** | 7 | deploy, list, rollback, validate, diff, finalize, promote |
| **API Keys** | 4 | list (masked), create, revoke, rotate |
| **Job Groups** | 6 | list, get, create, update, delete, stats |
| **Environments** | 5 | list, get, create, update, delete |
| **Projects** | 4 | list, get, create, settings |
| **Webhooks** | 7 | list, get, create, delete, deliveries, retry delivery, test |
| **Analytics** | 10 | performance, costs, cost trends, run summary, failure reasons, job history, reliability, top failing, workflow completion rates, step durations |
| **Usage** | 5 | current usage, history, forecast, project costs, spending anomalies |
| **Event Sources** | 5 | list, get, create, update, delete |
| **Notifications** | 4 | list, get, create, delete |
| **Log Drains** | 4 | list, get, create, delete |
| **Operations** | 2 | project status dashboard, OpenAPI spec |

### Resources (5)

| URI | Description |
|-----|-------------|
| `strait://connection` | Connection status, auth verification, API key scopes |
| `strait://health` | Infrastructure health: job counts, failure rate, scheduled runs |
| `strait://jobs` | Browseable list of all jobs with status, schedule, and run health |
| `strait://workflows` | Browseable list of all workflows with step count and status |
| `strait://analytics` | Current cost and performance snapshot (success rate, spend, top failures) |

### Prompts (9)

| Prompt | Arguments | Description |
|--------|-----------|-------------|
| `debug-failure` | `run_id` | Root cause analysis: fetches run + logs, reports what failed, why, and suggested fix |
| `optimize-cost` | `job_slug` | Cost analysis: reviews run history, suggests timeout/retry/concurrency optimizations |
| `incident-response` | (none) | Production incident investigation: check health, find failures, analyze root causes, recommend fixes |
| `setup-job` | `description` | Guided job creation from natural language: infers config, creates job, runs test, sets up monitoring |
| `cost-report` | `period?` | Comprehensive cost report: spend trends, top cost drivers, failure waste, projected costs |
| `workflow-status` | `workflow_run_id` | Workflow run deep-dive: step-by-step breakdown, bottlenecks, failure analysis |
| `deploy-preview` | `config` | Guided deployment: validate, diff, deploy with confirmation, monitor results |
| `onboard-project` | `name`, `description?` | New project setup: create project, test job, verify connectivity, suggest next steps |
| `security-audit` | (none) | Security review: API key health, secrets, webhook HTTPS compliance, spending anomalies |

### Error Handling

All errors are typed using Effect's tagged error pattern with automatic retry for transient failures:

| Error | Trigger | Response |
|-------|---------|----------|
| `NetworkError` | API unreachable | Base URL hint, check connectivity |
| `ApiError` | Non-2xx response | Status-specific hints (404: use list tool, 401: check scopes) |
| `RateLimitError` | 429 response | Parsed `Retry-After` header, automatic exponential backoff |
| `ValidationError` | Invalid input | Field name, constraint, example |
| `PollTimeoutError` | Watch timeout | Resource ID, elapsed time |

### Response Shaping

Every tool response is AI-optimized:

- Resource IDs in copyable form (`run_abc123`)
- Next-step hints ("Use `strait_get_run` with ID 'run_abc123' to check progress")
- Temporal context ("2m ago") instead of raw timestamps
- Lists capped at 25 items with cursor-based pagination
- Null/empty fields omitted

## Architecture

```
MCP Client <-- stdio or Streamable HTTP --> strait-mcp (Node.js) -- REST API --> Strait API
```

Built with:

- **[MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)** -- official TypeScript SDK for Model Context Protocol
- **[Effect](https://effect.website)** -- typed errors, dependency injection, structured concurrency
- **[Zod](https://zod.dev)** -- tool input schema validation (MCP SDK boundary)

## Development

```bash
bun install              # install dependencies
bun run dev              # stdio mode
bun run dev:http         # HTTP mode
bun run test             # run unit tests (304+ tests)
bun run test:integration # run integration tests (Docker required)
bun run typecheck        # type check with tsgo
bun run biome:lint       # lint with biome + ultracite
bun run biome:format     # format
bun run run-all          # lint + format + typecheck
```

### Project Structure

```
src/
  index.ts               -- entrypoint, transport selection, Effect runtime
  server.ts              -- McpServer creation, tool/resource/prompt registration
  config.ts              -- Effect config service
  errors.ts              -- tagged error taxonomy (NetworkError, ApiError, ...)
  schema.ts              -- slug, cron, step type validators
  types.ts               -- Strait domain model types
  client/
    service.ts            -- StraitClient Effect service tag
    http.ts               -- fetch-based implementation with retry/backoff
    jobs.ts ... apikeys.ts -- domain API functions returning Effects
  tools/
    helpers.ts            -- runEffect bridge, response shaping, formatError
    jobs.ts ... operations.ts -- MCP tool handlers
  resources/              -- strait://connection, strait://health
  prompts/                -- debug-failure, optimize-cost
tests/                   -- 221 tests with mock HTTP server
```

## Troubleshooting

### "STRAIT_API_KEY is required"

Set the environment variable before running, or pass it via the `env` block in your IDE config. Keys start with `strait_live_` or `strait_test_`.

### "NetworkError: API unreachable"

Check that `STRAIT_BASE_URL` is correct (defaults to `https://api.strait.dev`). If running behind a proxy, ensure outbound HTTPS is allowed.

### "ApiError: 401 Unauthorized"

Your API key may be expired or missing required scopes. Generate a new key at [strait.dev](https://strait.dev) with the scopes needed for the tools you are using.

### "ApiError: 404 Not Found"

The resource (job, run, workflow) does not exist or you lack access. Use the corresponding list tool to see available resources.

### "RateLimitError: 429"

The server retries automatically with exponential backoff. If this persists, reduce request frequency or contact support.

### MCP client does not detect the server

1. Verify the config file path is correct for your OS
2. Ensure `npx` is on your PATH (`which npx` to check)
3. Restart your IDE after changing MCP config
4. Check IDE logs for connection errors

### Docker container exits immediately

1. Ensure `STRAIT_API_KEY` is set: `docker run -e STRAIT_API_KEY=... ghcr.io/strait-dev/mcp`
2. Check logs: `docker logs <container-id>`
3. The default transport is HTTP on port 3000 -- ensure the port is not in use

## License

MIT