Authentication

The MCP server authenticates to the Nullstone API with an API key. It resolves the key and org in priority order:

1. Nullstone CLI profile (highest priority) — stored in ~/.nullstone/.
2. Environment variables — fallback.

Option 1 — CLI profile (recommended)

If you've already run nullstone configure on your machine, the MCP picks up the profile automatically. No extra configuration is needed in your MCP client.

nullstone configure --api-key=<your-api-key>
nullstone set-org <your-org>

Profiles are per-user and persist across sessions. When you switch orgs with nullstone set-org, the MCP sees the change on its next invocation.

Option 2 — environment variables

Useful for headless / CI scenarios, or when you want the MCP to use a different identity than your interactive CLI.

Variable	Purpose
NULLSTONE_API_KEY	API key. Required if no profile is present.
NULLSTONE_ORG	Org name. Required if no profile is present.
NULLSTONE_ADDR	API endpoint. Defaults to https://api.nullstone.io. Override for self-hosted.

Set these in your MCP client config:

{
  "mcpServers": {
    "nullstone": {
      "command": "/path/to/nullstone-mcp",
      "env": {
        "NULLSTONE_API_KEY": "nsk_…",
        "NULLSTONE_ORG": "acme"
      }
    }
  }
}

Getting an API key

1. Log in at app.nullstone.io.
2. Go to Account → API Keys.
3. Create a key. Copy it immediately — Nullstone will not show it again.

Org scoping

An MCP session is bound to one org. If your agent needs to operate across multiple orgs, register the MCP multiple times with different env blocks:

{
  "mcpServers": {
    "nullstone-acme": {
      "command": "/path/to/nullstone-mcp",
      "env": { "NULLSTONE_ORG": "acme", "NULLSTONE_API_KEY": "…" }
    },
    "nullstone-widgetco": {
      "command": "/path/to/nullstone-mcp",
      "env": { "NULLSTONE_ORG": "widgetco", "NULLSTONE_API_KEY": "…" }
    }
  }
}

Least-privilege guidance

For agent-driven workflows, prefer a dedicated service-account key scoped to the minimum required:

• Read-only agents (summaries, reports) — key with read scopes only.
• Deploy agents — read + deploy scopes, no envs_delete or apply on production stacks.
• Authoring agents (module publishing, IaC scaffolding) — read + module scopes.

Rotate keys regularly. API keys should never be committed to a repo — inject them via your MCP client's secret store.