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

# Set up the MCP server

> Register the Valkyrie MCP server in your client, with the transport and auth details.

## What you need

* A Valkyrie **MCP API key** (prefixed `vk_mcp_`), created on the
  [API Keys](https://docs.valkyrieapp.azumo.com/dashboard/api-keys.md) screen for the environment you want to operate.
* Your API base URL (e.g. `https://valkyrie-back.azumo.com`).

## Connection details that matter

The Valkyrie MCP endpoint has two specifics that trip people up:

> [!WARNING]
>
> 1. **Transport:** use **streamable HTTP** at the path **`/mcp-http/mcp`**.
> 2. **Auth:** your client must send the key in a request header on **every**
>    request, including each tool call. Use either `X-API-Key: YOUR_VALKYRIE_MCP_KEY`
>    or `Authorization: Bearer YOUR_VALKYRIE_MCP_KEY`.

The endpoint URL itself carries no credentials:

```text theme={null}
https://valkyrie-back.azumo.com/mcp-http/mcp
```

> [!NOTE]
>
> An `?api_key=` query parameter on the URL still works as a legacy fallback for
> existing clients. Avoid it for new setups. URLs are routinely written to server,
> proxy, and client logs, which exposes the key. When both a header and a query
> key are present, the header wins.

Remote requests that arrive without a key do **not** fall back to any key
configured on the Valkyrie server. Without a key, only public informational tools
such as `server_info` work. Every tool that reads or changes your resources
returns *"No API key configured."*

Keep the key out of committed config files. Where your client supports it, source
the header value from an environment variable or secret store.

## Claude Code

Pass the key with `--header`:

```bash theme={null}
claude mcp add --transport http valkyrie \
  https://valkyrie-back.azumo.com/mcp-http/mcp \
  --header "X-API-Key: $VALKYRIE_MCP_KEY"
```

Restart Claude Code and run `claude mcp list` to confirm it's connected.

## Claude Desktop

Claude Desktop's config file only accepts servers launched with a **command** (stdio),
not a bare remote `url`. If you add a `"url"` entry, the app silently drops it and its
log shows *"Skipped invalid MCP server config entries: valkyrie"*. Bridge the remote
Valkyrie endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), a small
stdio-to-HTTP bridge that `npx` downloads from npm on first run.

> [!NOTE]
>
> This path needs **Node.js** installed (it provides `npx`). It's the same Node runtime
> your other command-based MCP servers already use.

Edit Claude Desktop's config file:

* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Add Valkyrie under `mcpServers`. Use `mcp-remote`'s `--header` flag to send the key,
and reference it from `env` so the header value contains no spaces:

```json theme={null}
{
  "mcpServers": {
    "valkyrie": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://valkyrie-back.azumo.com/mcp-http/mcp",
        "--header",
        "X-API-Key:${VALKYRIE_MCP_KEY}"
      ],
      "env": {
        "VALKYRIE_MCP_KEY": "YOUR_VALKYRIE_MCP_KEY"
      }
    }
  }
}
```

Here `env` only feeds the `${VALKYRIE_MCP_KEY}` placeholder in the `--header`
argument. `mcp-remote` sends the actual header to Valkyrie.

Fully quit Claude Desktop (**Cmd+Q** on macOS, not just close the window) and reopen it.
Valkyrie then appears in your tools list. If it doesn't, check the log for a
`Skipped invalid MCP server config entries` line to confirm the entry is being read.

## Cursor

Add Valkyrie to Cursor's `mcp.json` with the streamable-HTTP URL and a `headers`
block:

```json theme={null}
{
  "mcpServers": {
    "valkyrie": {
      "url": "https://valkyrie-back.azumo.com/mcp-http/mcp",
      "headers": {
        "X-API-Key": "YOUR_VALKYRIE_MCP_KEY"
      }
    }
  }
}
```

## Verify it works

Connecting is not the same as being authenticated. `server_info` reporting that a key
was *supplied* does **not** mean the key is *valid*. To confirm, call a data tool such
as `list_deployments`:

* **Valid key** → returns your deployments.
* **Invalid key** → returns `{"error": "Invalid API key"}`.

> [!NOTE]
>
> Keys are **per-environment**. An MCP key from one environment returns
> *Invalid API key* against another. Issue the key from the dashboard of the
> environment you intend to operate.

## Troubleshooting

### Tools report "No API key configured"

The Valkyrie server didn't receive a key on that request. Check the following:

* Your client sends `X-API-Key` or `Authorization: Bearer` as a request **header**,
  not just on the initial connection.
* You haven't only set the key in the client's `env` block. For a remote server,
  `env` alone doesn't send anything to Valkyrie. It only helps when a header
  argument references it, as in the Claude Desktop example above.
* You aren't relying on a key configured on the Valkyrie server. Remote requests
  never inherit it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.