MCP servers

A hall declares its MCP servers once, in ivar.json, and ivar sync materialises them for every provider configured in the hall. The definitions are hall-scoped: a harness finds them by walking up from the view directory, so every session in the hall sees the same servers.

Declare them in ivar.json

A complete v5 hall manifest declaring all three harnesses (claude-code, opencode, and omp) and both HTTP endpoints (linear and figma) alongside a local tool. ivar graph index also declares the hall's own server, ivar (ivar graph mcp), which every provider gets as <hall>-ivar beside your servers. See Code graph over MCP.

{
  "$schema": "https://ivar.run/schema/5.json",
  "name": "acme",
  "providers": {
    "available": ["claude-code", "opencode", "omp"],
    "default": "claude-code"
  },
  "mcp": [
    {
      "name": "linear",
      "type": "http",
      "url": "https://mcp.linear.app/mcp"
    },
    {
      "name": "figma",
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    },
    {
      "name": "local-tools",
      "type": "local",
      "command": "npx",
      "args": ["-y", "@acme/tools-mcp"],
      "env": {
        "TOOLS_ENDPOINT": "ACME_TOOLS_ENDPOINT"
      }
    }
  ],
  "repos": [],
  "integration": {
    "via": "local",
    "strategy": "squash"
  },
  "version": 5
}

Configuration types

ivar.json strictly enforces canonical http and local definitions:

{
  "name": "linear",
  "type": "http",
  "url": "https://mcp.linear.app/mcp"
}

{
  "name": "local-tools",
  "type": "local",
  "command": "npx",
  "args": ["-y", "@acme/tools-mcp"],
  "env": {
    "TOOLS_ENDPOINT": "ACME_TOOLS_ENDPOINT"
  }
}

Provider translation table

ivar sync translates canonical manifest definitions into provider-native configurations:

Add, edit and remove

ivar mcp add declares a server in ivar.json and writes it into every provider's config. figma and linear are known names; any other HTTP server takes --url, and a stdio server takes --command with its arguments after --:

ivar mcp add figma
ivar mcp add sentry --url https://mcp.sentry.dev/mcp
ivar mcp add files --command npx -- -y @modelcontextprotocol/server-filesystem .
ivar mcp edit sentry --url https://eu.mcp.sentry.dev/mcp
ivar mcp remove files

ivar mcp edit replaces a server's URL or command. When the URL or the transport changes, the OAuth registration no longer applies: ivar drops it, deletes its client secret from .ivar/secrets/mcp.env unless another server uses it, and returns next: "ivar mcp auth <name>". ivar mcp remove takes the server out of ivar.json and every provider config and deletes its client secret on the same terms. Tokens a provider keeps in its own credential store stay there.

Naming and authentication commands

The name stored in ivar.json is canonical and unqualified (figma, linear). At every provider boundary, ivar qualifies the name with the hall name: <hall>-<server> (for example, acme-figma or acme-linear).

Use ivar mcp auth with the canonical name:

ivar mcp auth figma --provider claude-code   # authenticate specific provider
ivar mcp auth linear --provider opencode
ivar mcp auth figma --provider omp
ivar mcp auth figma --all-providers          # authenticate all configured providers

# Inspect credential status
ivar mcp status                              # all servers across all providers
ivar mcp status figma                        # specific server
ivar mcp status --provider claude-code       # specific provider
ivar mcp status --live                       # query provider harnesses live
ivar mcp status --json                       # emit JSON status matrix

Direct provider commands take the hall-qualified name only where the provider CLI natively exposes MCP login commands:

claude mcp login acme-figma                  # Claude Code native login
opencode mcp auth acme-linear                # OpenCode native auth

OMP exposes no MCP login command; authentication for OMP always runs through ivar mcp auth and persists credentials per hall under mcp_oauth_ivar:<hall>-<server> via omp auth-broker.

Provider support matrix

Claude Code

Claude Code reads .mcp.json at the hall root. ivar sync materialises hall-qualified names. When launching sessions, ivar supplies process-scoped settings --settings '{"enabledMcpjsonServers":["acme-linear","acme-figma",...]}' so declared servers are enabled without modifying global state. Claude Code owns its OAuth lifecycle directly via claude mcp login.

{
  "mcpServers": {
    "acme-linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp"
    },
    "acme-figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    },
    "acme-local-tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@acme/tools-mcp"
      ],
      "env": {
        "TOOLS_ENDPOINT": "ACME_TOOLS_ENDPOINT"
      }
    }
  }
}

OpenCode

OpenCode reads opencode.json at the hall root. For standard services like Linear, OpenCode manages OAuth directly via opencode mcp auth acme-linear. For Figma, Ivar performs prerequisite registration and OAuth token acquisition, storing tokens in OpenCode's credential store (mcp-auth.json).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "acme-linear": {
      "type": "remote",
      "url": "https://mcp.linear.app/mcp"
    },
    "acme-figma": {
      "type": "remote",
      "url": "https://mcp.figma.com/mcp",
      "oauth": {
        "clientId": "<generated_client_id>",
        "clientSecret": "{env:IVAR_MCP_ACME_FIGMA_SECRET}",
        "redirectUri": "http://127.0.0.1:19876/callback"
      }
    },
    "acme-local-tools": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@acme/tools-mcp"
      ],
      "environment": {
        "TOOLS_ENDPOINT": "{env:ACME_TOOLS_ENDPOINT}"
      }
    }
  }
}

OMP

OMP reads .omp/mcp.json at the hall root, ahead of opencode.json's mcp entries. Because OMP has no built-in mcp login CLI command, ivar mcp auth always runs Ivar's internal OAuth PKCE engine for OMP, then imports the resulting tokens per hall under mcp_oauth_ivar:<hall>-<server> directly via omp auth-broker.

ivar sync writes an auth block for every http server in .omp/mcp.json, with type: "oauth" and credentialId: "mcp_oauth_ivar:<hall>-<server>". When persisted OAuth metadata contains a token_url, the block also carries clientId, clientSecret (as ${VAR}), tokenUrl, and resource.

{
  "mcpServers": {
    "acme-linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "auth": {
        "type": "oauth",
        "credentialId": "mcp_oauth_ivar:acme-linear",
        "clientId": "<generated_client_id>",
        "tokenUrl": "<discovered-token-endpoint>"
      }
    },
    "acme-figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp",
      "auth": {
        "type": "oauth",
        "credentialId": "mcp_oauth_ivar:acme-figma",
        "clientId": "<generated_client_id>",
        "clientSecret": "${IVAR_MCP_ACME_FIGMA_SECRET}",
        "tokenUrl": "<discovered-token-endpoint>"
      }
    },
    "acme-local-tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@acme/tools-mcp"
      ],
      "env": {
        "TOOLS_ENDPOINT": "ACME_TOOLS_ENDPOINT"
      }
    }
  }
}

OAuth metadata and secrets

When ivar mcp auth discovers endpoints or performs dynamic client registration, it persists client and endpoint metadata back to ivar.json under the server entry:

{
  "name": "figma",
  "type": "http",
  "url": "https://mcp.figma.com/mcp",
  "oauth": {
    "client_id": "<generated_client_id>",
    "client_secret_env": "IVAR_MCP_ACME_FIGMA_SECRET",
    "token_url": "<discovered-token-endpoint>",
    "resource": "<discovered-resource>"
  }
}

Service nuances: Linear vs. Figma

Linear

Linear implements standard RFC 8414 OAuth 2.0 authorization server metadata and RFC 7591 dynamic client registration for public clients (token_endpoint_auth_method: "none"). No pre-shared client credentials or allowlist workarounds are required. Claude Code and OpenCode authenticate natively, while OMP utilizes Ivar's generic PKCE registration and token installation.

Figma

Figma restricts Dynamic Client Registration (DCR) to allowlisted client_name values (such as "Claude Code" and "Codex"). Generic or unrecognized client names receive 403 Forbidden. Furthermore, Figma requires a client secret during token exchange despite advertising public authentication.

To support OpenCode and OMP:

1. ivar mcp auth registers a client using an allowlisted client name (Codex).
2. Ivar persists the registration metadata in ivar.json and saves the secret reference to .ivar/secrets/mcp.env.
3. Ivar runs the browser OAuth PKCE exchange and imports credentials directly to the respective harness stores.