MCP (Model Context Protocol)

DojOps supports the Model Context Protocol  (MCP) — a Linux Foundation standard for connecting LLMs to external tool servers. MCP enables the autonomous agent (dojops auto) to call tools from databases, cloud APIs, GitHub, and any MCP-compatible server.

Overview

MCP extends the agent loop beyond the 7 built-in tools (read_file, write_file, edit_file, run_command, run_skill, search_files, done) with tools from external servers. The @dojops/mcp package handles server lifecycle, tool discovery, and dispatch.

Key concepts:

• Transports: stdio (spawn a local process) or streamable-http (connect to a remote endpoint)
• Tool namespacing: MCP tools appear as mcp__<server>__<tool> (e.g., mcp__github__create_issue)
• Non-fatal: MCP is optional — connection failures are silently skipped, and the agent continues with built-in tools

Configuration

MCP servers are configured in JSON files at two levels:

• Project: .dojops/mcp.json — scoped to the current project
• Global: ~/.dojops/mcp.json — shared across all projects

Project config overrides global by server name when both define the same server.

Config Format

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {}
    },
    "remote-api": {
      "transport": "streamable-http",
      "url": "http://localhost:8080/mcp",
      "headers": {}
    }
  }
}

Stdio Transport

Spawns a local process that communicates over stdin/stdout:

Streamable HTTP Transport

Connects to a remote MCP server over HTTP:

CLI Commands

List Servers

dojops mcp list

Shows all configured servers with transport type and connection details. Tests connections and reports available tool count.

Add a Server

dojops mcp add

Interactive prompts for:

1. Server name (lowercase alphanumeric, hyphens, underscores)
2. Transport type (stdio or streamable-http)
3. Command and arguments (stdio) or URL (HTTP)

Remove a Server

dojops mcp remove [name]

Removes a server from .dojops/mcp.json. If no name is provided, shows an interactive picker.

Agent Integration

When dojops auto starts, it:

1. Loads MCP config from .dojops/mcp.json and ~/.dojops/mcp.json
2. Connects to all configured servers (failures silently skipped)
3. Discovers tools from each server via listTools()
4. Merges MCP tools with the 7 built-in agent tools
5. Passes the McpToolDispatcher to ToolExecutor
6. Disconnects all servers in a finally block on completion

The ToolExecutor dispatch chain:

built-in tools → skill resolution → MCP dispatcher → "Unknown tool" error

Example

# Configure a filesystem MCP server
cat > .dojops/mcp.json << 'EOF'
{
  "mcpServers": {
    "memory": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}
EOF
 
# The agent can now use memory tools
dojops auto "Store a note about our deployment process and retrieve it"
# Agent discovers: mcp__memory__read_memory, mcp__memory__write_memory

Architecture

┌─────────────────────────────────────────────────┐
│  dojops auto "prompt"                           │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│  AgentLoop                                      │
│  LLM sees: 7 built-in tools + N MCP tools       │
└────────┬──────────────────────┬─────────────────┘
         │                      │
         ▼                      ▼
┌────────────────┐    ┌──────────────────────────┐
│ Built-in tools │    │ McpToolDispatcher         │
│ (ToolExecutor) │    │ ─ Parses mcp__srv__tool   │
│                │    │ ─ Routes to McpClientMgr  │
└────────────────┘    └──────────┬───────────────┘
                                 │
                    ┌────────────┴────────────┐
                    │   McpClientManager      │
                    │   ─ stdio transport     │
                    │   ─ HTTP transport      │
                    │   ─ Tool discovery      │
                    └─────────────────────────┘

Popular MCP Servers

Browse more at modelcontextprotocol.io/servers .

DojOps as MCP server

DojOps can also run as an MCP server, exposing its capabilities to external CLI agents like Claude Code, Gemini CLI, GitHub Copilot, and OpenClaw.

Starting the server

# Via the CLI (requires dojops serve running separately on port 3000)
dojops serve --mcp
 
# Standalone (same behavior)
npx @dojops/mcp

The MCP server uses stdio transport and proxies all requests to a running dojops serve instance (default http://localhost:3000).

Exposed tools

Configuring external agents

Claude Code (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "dojops": {
      "command": "dojops",
      "args": ["serve", "--mcp"]
    }
  }
}

Gemini CLI (.gemini/settings.json):

{
  "mcpServers": {
    "dojops": {
      "command": "npx",
      "args": ["@dojops/mcp"]
    }
  }
}

GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "dojops": {
      "command": "dojops",
      "args": ["serve", "--mcp"]
    }
  }
}

Environment variables

Architecture

External Agent (Claude Code / Gemini CLI / Copilot)
  |
  v  stdio (JSON-RPC)
DojOps MCP Server (dojops serve --mcp)
  |
  v  HTTP
DojOps API (dojops serve, port 3000)
  |
  v
LLM Provider → Agent Router → Skill Engine → Executor

The MCP server is a thin proxy layer. It translates MCP tool calls into HTTP requests to the DojOps REST API and returns the results. All the actual processing (agent routing, skill matching, LLM generation, validation) happens in the running dojops serve instance.