/harness-mcp

Use this skill to create, edit, and manage mcp entities in the agent-harness workspace. An mcp entity defines one or more MCP (Model Context Protocol) servers in a single JSON config file. When harness apply runs, all mcp config files are merged and rendered into each enabled provider's native format.

What is an mcp entity?

An mcp entity is a JSON file under .harness/src/mcp/<config-id>.json. It contains a map of server definitions keyed by server ID. Multiple mcp config files are supported — harness merges them at apply time. If the same server ID appears in more than one file, harness rejects the plan with a collision error.

Source path: .harness/src/mcp/<config-id>.json

The file is a flat JSON object where each top-level key is a server ID and its value is the server definition. Any key-shape that does not use a reserved wrapper key (servers or mcpServers) is treated as a direct server map; files that happen to use those wrapper keys are unwrapped automatically before merging.

Provider output mapping

Claude Code — .mcp.json

Root key: mcpServers. Each server entry supports:

Project-scoped MCP servers live in .mcp.json at the repo root. This is the file harness writes.

Official docs: https://code.claude.com/docs/en/mcp

OpenAI Codex CLI — .codex/config.toml

Section: [mcp_servers.<id>]. Fields rendered by harness are command, args, and env. The full field set supported by Codex config includes:

Official docs: https://developers.openai.com/codex/config-reference

GitHub Copilot — .vscode/mcp.json

Root key: servers. Each server entry supports:

Official docs: https://code.visualstudio.com/docs/copilot/chat/mcp-servers

Cursor — .cursor/mcp.json

Root key: mcpServers. Each server entry supports:

Cursor supports three transport methods: stdio (local), SSE (local/remote), and Streamable HTTP (local/remote). Protocol capabilities include tools, prompts, resources, roots, elicitation, and MCP apps (interactive UI extension).

Configuration locations: project (.cursor/mcp.json) or global (~/.cursor/mcp.json).

Config interpolation supported in command, args, env, url, and headers:

• ${env:NAME} — environment variables
• ${userHome} — home directory
• ${workspaceFolder} — project root
• ${workspaceFolderBasename} — project root name
• ${pathSeparator} / ${/} — OS path separator

Official docs: https://docs.cursor.com/context/mcp

Canonical source format

The harness source file is a plain JSON object. Use one server-ID key per server you want to register:

{
  "<server-id>": {
    "command": "...",
    "args": ["..."],
    "env": {
      "VAR_NAME": "value"
    }
  }
}

You may define as many servers as needed in one file, or split them across multiple mcp entity files. Harness merges all files before rendering — server IDs must be unique across all files.

Remote server URLs

For sse / http transport servers, write the endpoint under url — every supported provider (Claude Code, OpenAI Codex CLI, GitHub Copilot, Cursor) reads a remote server's endpoint from a field named url, never serverUrl. As a compatibility alias, harness accepts serverUrl in the source file and rewrites it to url in every rendered artifact, but new configs should use url directly:

{
  "figma": {
    "url": "https://mcp.figma.com/mcp"
  }
}

Harness CLI commands

# Scaffold a new mcp config file and register it in the manifest
npx harness add mcp <config-id>

# After editing the source file, generate provider artifacts
npx harness apply

# Preview what apply will do (no writes)
npx harness plan

# Remove an mcp entity and its source file
npx harness remove mcp <config-id>

# Remove entity but keep the source file
npx harness remove mcp <config-id> --no-delete-source

Copy-paste example

.harness/src/mcp/servers.json — a filesystem server and a Postgres server:

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
    "env": {}
  },
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "POSTGRES_CONNECTION_STRING": "${POSTGRES_CONNECTION_STRING}"
    }
  }
}

After running npx harness apply, harness writes:

.mcp.json (Claude Code):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "actual-value-from-env"
      }
    }
  }
}

.codex/config.toml (Codex CLI):

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]

[mcp_servers.postgres.env]
POSTGRES_CONNECTION_STRING = "actual-value-from-env"

.vscode/mcp.json (GitHub Copilot):

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "actual-value-from-env"
      }
    }
  }
}

Environment variable substitution

Use ${ENV_VAR_NAME} placeholders anywhere in the JSON values. Harness substitutes them at apply time using the process environment. This keeps secrets out of source-controlled files.

{
  "my-api-server": {
    "command": "npx",
    "args": ["-y", "my-mcp-server"],
    "env": {
      "API_KEY": "${MY_API_KEY}",
      "BASE_URL": "${MY_API_BASE_URL}"
    }
  }
}

If a referenced variable is not set in the environment, harness will error during apply.

Typical workflow

# 1. Enable providers (once per project)
npx harness provider enable claude
npx harness provider enable codex
npx harness provider enable copilot

# 2. Scaffold the config file
npx harness add mcp servers

# 3. Edit .harness/src/mcp/servers.json with your server definitions

# 4. Review the plan
npx harness plan

# 5. Write provider artifacts
npx harness apply

Official documentation

• Claude Code MCP: https://code.claude.com/docs/en/mcp
• Claude Code Settings: https://code.claude.com/docs/en/settings
• OpenAI Codex Config Reference: https://developers.openai.com/codex/config-reference
• GitHub Copilot MCP (VS Code): https://code.visualstudio.com/docs/copilot/chat/mcp-servers
• Cursor MCP: https://docs.cursor.com/context/mcp