API keys and service accounts

The API Keys page has two credential types:

• Agent public keys (mcpstack_pk_*) are publishable browser keys for @mcpstack/agent-sdk embeds. They are scoped to one agent and restricted by allowed browser origins.
• Service-account keys (mcpstack_sk_*) are secrets for CI pipelines, scripts, backend jobs, and telemetry. Each service key is tied to an organization role and enforced through the same permission model as human members.

Requirements#

• Owner or Admin access to create keys (Developers can use keys they are granted)
• an organization ID for --org or MCPSTACK_ORG_ID
• a clear key name so rotation is auditable

Dashboard path#

The API Keys page lists active keys, roles, and last-used timestamps.

1. Open API Keys from the dashboard sidebar.
2. In Service account keys, click Create service key.
3. Enter a descriptive name (for example ci-smoke-prod).
4. Choose a role (typically Developer for automation that manages servers and agents).
5. Copy the secret immediately — MCP Stack shows it only once.
6. Store the secret in your CI secret manager.

Revoke keys you no longer need from the same page.

To embed an agent in a browser, use Create public key instead. First verify the customer domain from the agent's Embed tab, then choose the agent, enter exact allowed origins such as https://app.example.com, and copy the resulting mcpstack_pk_* value. Public keys remain visible so embed snippets can be recovered later; service-account secrets do not.

CLI path#

Human login for local work:

npm install -g @mcpstack/cli
mcpstack auth login
mcpstack org list
mcpstack api-keys list --org org_123

Create and use a service-account key:

mcpstack api-keys create --name automation-bot --role developer
mcpstack api-keys list
 
export MCPSTACK_API_KEY=mcpstack_sk_xxxx
mcpstack auth service-account login --key "$MCPSTACK_API_KEY"
mcpstack servers list --json

API path#

List keys:

GET /api/v1/organizations/{orgId}/api-keys
Authorization: Bearer {token}

Create a key:

POST /api/v1/organizations/{orgId}/api-keys
Authorization: Bearer {token}
Content-Type: application/json
 
{
  "name": "automation-bot",
  "role": "developer"
}

The response includes the secret once. Revoke with:

DELETE /api/v1/organizations/{orgId}/api-keys/{keyId}
Authorization: Bearer {token}

Automation can authenticate with Authorization: Bearer {api-key} or X-API-Key on management APIs.

Security notes#

Troubleshooting#

Related#

• Use the MCP Stack CLI
• Organization roles and billing access
• Security and identity model

Quick answer#

Use service-account keys for automation. Use agent public keys for browser embeds. Never put an mcpstack_sk_* service-account secret in frontend code.