Authentication & configuration
Configure the Layers MCP server with flags or environment variables — API key, base URL, read-only mode, and acting on behalf of a child organization.
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 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 for key format and scopes, and API keys for the lifecycle.
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 for the full behavior contract.
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.
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.
npx -y @layers/mcp-server@latest --api-key lp_YOUR_KEY --read-onlyActing as a child organization
If you manage customers as sub-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.
npx -y @layers/mcp-server@latest --api-key lp_PARENT_ADMIN_KEY --organization org_CHILD_IDSecurity
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 anenvblock. The 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-onlywhen no writes are required. - If a key leaks, revoke it — see API keys.
Quickstart
Connect the Layers MCP server to Claude or the OpenAI Agents SDK with a single npx command, then ask your agent to run whoami.
How it works
Transport, server instructions, tool annotations, async jobs, pagination, idempotency, errors, and timestamps — the conventions every Layers MCP tool follows.