> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getovra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP setup

> Connect @ovra/mcp to any MCP-compatible client in under a minute.

Two transports, three steps, one minute. Start with Streamable HTTP for production and stdio for desktop dev.

<Note>
  Use a `sk_sandbox_*` or `sk_test_*` key. The server validates your key on startup and exits if it's invalid or revoked.
</Note>

## Streamable HTTP (recommended)

No local install. Add to your client config:

```json theme={}
{
  "mcpServers": {
    "ovra": {
      "type": "streamable-http",
      "url": "https://api.getovra.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_sandbox_..."
      }
    }
  }
}
```

## Stdio (local subprocess)

Runs the server via npx — no global install required.

```json theme={}
{
  "mcpServers": {
    "ovra": {
      "command": "npx",
      "args": ["@ovra/mcp@latest"],
      "env": {
        "OVRA_API_KEY": "sk_sandbox_..."
      }
    }
  }
}
```

## Where the config lives

| Client                   | Path                                                              |
| ------------------------ | ----------------------------------------------------------------- |
| Claude Desktop (macOS)   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json`                     |
| Claude Desktop (Linux)   | `~/.config/Claude/claude_desktop_config.json`                     |
| Cursor                   | `~/.cursor/mcp.json`                                              |
| Other                    | See your client docs                                              |

## Environment variables

| Variable           | Required    | Default                   | Description                                                |
| ------------------ | ----------- | ------------------------- | ---------------------------------------------------------- |
| `OVRA_API_KEY`     | Yes (stdio) | –                         | `sk_sandbox_*` / `sk_test_*` / `sk_live_*` (live in v1.3+) |
| `OVRA_AGENT_TOKEN` | Optional    | –                         | Use an `at_*` agent-scoped token instead of an API key     |
| `OVRA_API_URL`     | No          | `https://api.getovra.com` | Override base URL                                          |

You can use **either** `OVRA_API_KEY` (org-wide) **or** `OVRA_AGENT_TOKEN` (single-agent). Agent tokens give the LLM strict isolation — it sees only that one agent's cards, intents, and transactions.

## Verify

After restart your client should expose 19 `ovra_*` tools. Smoke-test with:

```text theme={}
List my agents using ovra_agent action "get".
```

If the tool list is empty:

1. Check the `Authorization` header / `OVRA_API_KEY` env value is set correctly.
2. Confirm the key isn't revoked (`GET /keys` returns the active list).
3. Tail your client's MCP logs — auth failures surface as `401` from the bootstrap call.

## Startup sequence

<Steps>
  <Step title="Read credentials">
    Server reads `OVRA_API_KEY` or `OVRA_AGENT_TOKEN` from env (stdio) or `Authorization` header (HTTP).
  </Step>

  <Step title="Health check">
    Boot calls `GET /health` with the credential to validate.
  </Step>

  <Step title="Register tools">
    Valid credential → register all 19 tools with their schemas. Invalid → exit with a clear error.
  </Step>

  <Step title="Ready">
    Client begins discovering tools.
  </Step>
</Steps>

## Security in MCP

* Every tool response goes through `redact()` before reaching the model.
* Destructive actions require `confirm: true`.
* IDs are sanitized against path traversal.
* Webhook and execute URLs must be HTTPS and SSRF-safe.

## Next

<CardGroup cols={2}>
  <Card title="Tool reference" icon="book" href="/mcp/tools">
    Every action and parameter.
  </Card>

  <Card title="MCP overview" icon="info" href="/mcp/overview">
    Architecture, security, supported clients.
  </Card>

  <Card title="Claude Desktop" icon="comments" href="/integrations/claude-desktop">
    Step-by-step desktop setup.
  </Card>
</CardGroup>