# Overview
> Declare MCP servers once in your hall manifest, sync configs across all coding agent providers, and manage authentication workflows cleanly.
Source: https://ivar.run/docs/guide/mcp

import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';

Model Context Protocol (MCP) gives your coding agents access to external tools, APIs, and services. In a multi-repo hall, manually maintaining distinct MCP configuration files for each agent tool creates drift and credential leaks.

Ivar standardizes MCP across your team through a three-step workflow:

1. **Declare once**: Define all external tools and services centrally in `ivar.json` using canonical names and transport types (`http` or `local`).
2. **Sync**: Generate provider-native configurations (`.mcp.json`, `opencode.json`, hall-root `mcp.json`) on every `ivar sync`.
3. **Authenticate**: Handle authentication workflows using unified CLI commands without storing plaintext secrets in source control.

## Unified manifest

Add your MCP servers under the `mcp` array in `ivar.json`. Canonical declarations use generic `http` or `local` types:

```json title="ivar.json"
{
  "$schema": "https://ivar.run/schema/4.json",
  "name": "acme",
  "providers": {
    "available": ["claude-code", "opencode", "omp"],
    "default": "claude-code"
  },
  "mcp": [
    {
      "name": "figma",
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    },
    {
      "name": "linear",
      "type": "http",
      "url": "https://mcp.linear.app/mcp"
    }
  ],
  "repos": [],
  "integration": {
    "via": "local",
    "strategy": "squash"
  },
  "version": 4
}
```

<Callout type="info" title="Canonical vs. hall-qualified names">
  In `ivar.json`, declare tools by their canonical names (such as `figma` or `linear`). During provider sync, Ivar automatically qualifies server names with your hall prefix (for example, `acme-figma` and `acme-linear`) to avoid collisions.
</Callout>

## Syncing provider configs

Run `ivar sync` to generate configuration for all declared providers:

```bash
ivar sync
```

Ivar maps each canonical server to provider-specific schemas:
- **Claude Code**: writes `.mcp.json` with hall-qualified keys.
- **OpenCode**: updates the `mcp` section in `opencode.json`.
- **Oh My Pi (OMP)**: writes hall-root `mcp.json` and bridges profiles.

## Inspecting authentication status

Check the credential status of all declared MCP servers across configured providers using `ivar mcp status`:

```bash
# Check local status for all servers and providers
ivar mcp status

# Check a specific server or provider
ivar mcp status figma
ivar mcp status --provider claude-code

# Query provider harnesses for live connectivity status
ivar mcp status --live

# Emit machine-readable status matrix
ivar mcp status --json
```

### Credential states

| State | Meaning | Source | Action |
| --- | --- | --- | --- |
| `authenticated` | Valid credentials are present in the provider store. | `local` / `live` | Ready to use. |
| `missing` | No credential found or access token is empty. | `local` / `live` | Run `ivar mcp auth <server> --provider <p>`. |
| `expired` | Access token past its expiry, refresh token present (claude-code, opencode). | `local` | The harness can refresh it on its next connection. Confirm with `ivar mcp status --live`, or run `ivar mcp auth <server> --provider <p>`. |
| `unknown` | Store unreadable or harness text output unrecognized. | `local` / `live` | Try `ivar mcp status --live` or re-authenticate. |
| `not-required` | Server is `type: "http"` with no OAuth requirements. | `local` | None needed. |
| `not-applicable` | Server is `type: "local"` (command spawned locally). | `local` | None needed. |

`ivar doctor` checks for `missing` credentials across all declared servers during health checks.

## Authenticating services

Authenticate individual providers or all configured providers using `ivar mcp auth`:

```bash
# Authenticate a specific provider for a canonical integration
ivar mcp auth figma --provider claude-code
ivar mcp auth linear --provider opencode
ivar mcp auth figma --provider omp

# Authenticate all configured providers at once
ivar mcp auth figma --all-providers
```

Direct provider commands take the **hall-qualified** name when using native CLI authentication:

```bash
claude mcp login acme-figma
opencode mcp auth acme-linear
```

## Explore MCP guides

<Cards>
  <Card
    title="Provider Guides"
    href="/docs/guide/mcp/providers/claude-code"
    description="Set up and configure Claude Code, OpenCode, and OMP for MCP."
  />
  <Card
    title="Integrations"
    href="/docs/guide/mcp/integrations/figma"
    description="Connect Figma and Linear MCP servers to your hall agents."
  />
  <Card
    title="Code graph"
    href="/docs/guide/graph"
    description="Serve the hall's code graph to agents as a local MCP server."
  />
  <Card
    title="Authentication"
    href="/docs/guide/mcp/oauth"
    description="Understand Dynamic Client Registration, PKCE flows, and token persistence."
  />
  <Card
    title="MCP Schema Reference"
    href="/docs/reference/mcp"
    description="Inspect full schema definitions, field reference, and provider translation tables."
  />
</Cards>