# Authentication & configuration (/docs/api/mcp-server/authentication)



The server is configured at launch. Every option has a CLI flag and an environment variable; **flags take precedence, env vars are the fallback.**

| Flag             | Env var               | Default                  | Description                                                                                                                     |
| ---------------- | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `--api-key`      | `LAYERS_API_KEY`      | — *(required)*      | Partner API key (`lp_...`). The server exits non-zero if it's missing.                                                          |
| `--base-url`     | `LAYERS_BASE_URL`     | `https://api.layers.com` | API host. Paths are versioned under `/v1`.                                                                                      |
| `--read-only`    | `LAYERS_READ_ONLY=1`  | off                      | Registers **only the 25 read tools**; the 27 mutating tools are not exposed at all.                                             |
| `--organization` | `LAYERS_ORGANIZATION` | unset                    | Act on behalf of a child org (`org_...`), sent as `X-Layers-Organization` on every request. Requires an `org:admin` parent key. |

## The API key determines everything [#the-api-key-determines-everything]

The key you pass is the entire identity and permission boundary. Its organization, scopes, and rate-limit tier all apply exactly as they do for direct API calls — the MCP server adds no privileges of its own. A key scoped to read-only data can't be coaxed into writing by the agent; a sandbox key stays in the sandbox.

See [Authentication](/docs/api/getting-started/authentication) for key format and scopes, and [API keys](/docs/api/concepts/api-keys) for the lifecycle.

## Sandbox keys [#sandbox-keys]

A `lp_test_...` key puts the whole surface in sandbox mode: content generation, OAuth connection, and publishing return **fixture-backed results** and nothing reaches real social accounts. This is the safe way to develop and test an agent end-to-end.

Sandbox keys default to tighter rate limits than live keys. See [Sandbox](/docs/api/concepts/sandbox) for the full behavior contract.

## Read-only mode [#read-only-mode]

Pass `--read-only` (or `LAYERS_READ_ONLY=1`) to register **only** the read tools. The 27 mutating tools aren't just blocked — they're never advertised to the client, so the agent can't see or attempt them.

<Callout type="info">
  Read-only mode is a belt-and-suspenders control on top of key scopes. Use it
  when you want a hard guarantee that an agent can observe but never change
  state — for analytics assistants, demos, or untrusted prompts.
</Callout>

```sh
npx -y @layers/mcp-server@latest --api-key lp_YOUR_KEY --read-only
```

## Acting as a child organization [#acting-as-a-child-organization]

If you manage customers as [sub-organizations](/docs/api/concepts/organizations), pass `--organization org_...` to act on a child org. The server sends it as the `X-Layers-Organization` header on every request. This requires an `org:admin` **parent** key — the same control-plane credential you'd use to call the API on a child's behalf directly.

```sh
npx -y @layers/mcp-server@latest --api-key lp_PARENT_ADMIN_KEY --organization org_CHILD_ID
```

## Security [#security]

The API key is a secret. When passed as `--api-key`, it appears in the client's stored config and in the process's command line — visible to anything that can run `ps`.

* **Prefer the env-var path** (`LAYERS_API_KEY`) wherever the client supports an `env` block. The [Quickstart](/docs/api/mcp-server/quickstart) configs use it by default.
* **Use a sandbox key** (`lp_test_...`) for development so a leak is low-impact.
* **Scope the key down** to only what the agent needs, and pair it with `--read-only` when no writes are required.
* If a key leaks, revoke it — see [API keys](/docs/api/concepts/api-keys).