Installation

OPLINK is an MCP server you run alongside your editor. It reads workflows from a .mcp-workflows directory and exposes them as tools to your IDE/agent.

There are two typical ways to install it:

Path A – MCP server only (most users)

If you just want to use workflows (not scaffold templates), you can:

1. Create a .mcp-workflows directory in your project.
   • Add .mcp-workflows/workflows.yaml (and servers.json if using external servers).
   • Add .mcp-workflows/.env if you need environment variables (API keys, tokens, etc.).
2. Point your IDE or MCP client at:

   npx -y oplink@latest server --config ./.mcp-workflows
   

You never have to run init if you're comfortable creating those files yourself.

Note: The .env file should be placed inside the .mcp-workflows directory (the same directory you pass to --config). Oplink automatically loads .env files from this directory before expanding ${VAR} placeholders in servers.json.

⚠️ Security Warning: Never commit .env files to version control. Add .mcp-workflows/.env to your .gitignore file to prevent accidentally committing sensitive credentials.

Path B – CLI + templates (full authoring)

If you want the CLI helpers (init, validate, add examples, bundled JSON Schemas), run:

npx -y oplink@latest init

This will:

1. Create a .mcp-workflows directory (if needed).
2. Scaffold workflows.yaml and servers.json examples.
3. Copy JSON Schemas into schema/ for editor validation.

After that:

1. Create .mcp-workflows/.env if you need environment variables (API keys, tokens, etc.).
2. Commit .mcp-workflows (and schema/ if you want schema validation in CI). Do not commit .env files — add them to .gitignore.
3. Point your IDE entry to --config ./.mcp-workflows.

Note: The .env file must be placed inside the .mcp-workflows directory (the same directory you pass to --config). Oplink automatically loads .env files from this directory before expanding ${VAR} placeholders in servers.json.

⚠️ Security Warning: Never commit .env files to version control. Add .mcp-workflows/.env to your .gitignore file to prevent accidentally committing sensitive credentials.

Table of Contents

• Requirements
• Choose Your Path
• Install in Your IDE
  • Cursor
  • Codex CLI
  • Claude Code
  • Cline
  • GitHub Copilot (VS Code)

Install in Your IDE

Use these minimal, copy‑pasteable setups. Each IDE section is collapsible.

{
  "mcpServers": {
    "oplink": {
      "command": "npx",
      "args": ["oplink@latest", "server", "--config", "./.mcp-workflows"],
      "env": {}
    }
  }
}

codex mcp add oplink -- npx -y oplink@latest server --config /absolute/path/to/.mcp-workflows

claude mcp add oplink -- npx -y oplink@latest server --config /absolute/path/to/.mcp-workflows

claude mcp add-json oplink '{"type":"stdio","command":"npx","args":["oplink@latest","server","--config","/absolute/path/to/.mcp-workflows"]}'

{
  "mcpServers": {
    "oplink": {
      "command": "npx",
      "args": ["oplink@latest", "server", "--config", "./.mcp-workflows"],
      "transportType": "stdio",
      "timeout": 60,
      "env": {}
    }
  }
}

{
  "servers": {
    "oplink": {
      "type": "stdio",
      "command": "npx",
      "args": ["oplink@latest", "server", "--config", "./.mcp-workflows"]
    }
  }
}

Additional Options

To add example workflows from a remote (giget) source:

npx oplink@latest add github:user/repo/path#ref

Editor IntelliSense (optional, recommended)

Enable completions/validation for your YAML files:

• Add a modeline at the top of .mcp-workflows/workflows.yaml:

  # yaml-language-server: $schema=../schema/oplink-workflows.schema.json
  

• Add $schema to .mcp-workflows/servers.json:

  { "$schema": "../schema/oplink-servers.schema.json", "servers": { /* ... */ } }
  

• Or map schemas in VS Code workspace settings:

  {
    "yaml.schemas": {
      "./schema/oplink-workflows.schema.json": ".mcp-workflows/workflows.yaml",
      "./schema/oplink-servers.schema.json": ".mcp-workflows/servers.json"
    }
  }