> ## Documentation Index > Fetch the complete documentation index at: https://docs.hq.zone/llms.txt > Use this file to discover all available pages before exploring further. # Set an MCP server API key > Stores an API key credential for an MCP server and installs/enables it in one call, for servers whose credential model is tenant_api_key only. The scope may be team (shared across the workspace, the default) or user (private to the caller); the chosen scope must be among the server's allowed scopes, and user scope requires a resolvable calling user. The supplied key is securely sealed and, where the backend supports it, validated against the upstream before being saved; an invalid key is rejected. Idempotent: pasting a new key for an existing install rotates the credential in place. Returns the slug, enabled flag, the stored credential reference id, and the confirmed scope. Admin only; scoped to the caller's own workspace. ## OpenAPI ````yaml POST /v1/mcp/installs/{slug}/api_key openapi: 3.1.0 info: title: HQ API description: >- Public HTTP API for HQ. Authenticate with a Personal Access Token (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's behalf. Both grant from the same resource:action scope vocabulary; an endpoint's required scope is listed under its `security`. license: name: Apache-2.0 identifier: Apache-2.0 version: 1.0.0 servers: - url: https://api.hq.zone description: HQ API (production) security: [] tags: - name: me description: The signed-in user's own account - name: conversations description: Conversations and their messages - name: documents description: The content-addressed documents library - name: schedules description: Scheduled prompts and recurring tasks - name: agents description: Agents, their skills and integrations - name: memory description: What the assistant remembers (L5 governance) - name: tokens description: Personal Access Token management - name: billing description: Usage and billing - name: notifications description: In-app notification center - name: admin description: Workspace administration - name: integrations description: Workspace integrations (Slack, MCP, skills) - name: onboarding description: New-workspace onboarding wizard - name: auth description: Sign-in, sessions, and OAuth paths: /v1/mcp/installs/{slug}/api_key: post: tags: - integrations summary: Set an MCP server API key description: >- Stores an API key credential for an MCP server and installs/enables it in one call, for servers whose credential model is tenant_api_key only. The scope may be team (shared across the workspace, the default) or user (private to the caller); the chosen scope must be among the server's allowed scopes, and user scope requires a resolvable calling user. The supplied key is securely sealed and, where the backend supports it, validated against the upstream before being saved; an invalid key is rejected. Idempotent: pasting a new key for an existing install rotates the credential in place. Returns the slug, enabled flag, the stored credential reference id, and the confirmed scope. Admin only; scoped to the caller's own workspace. operationId: set_mcp_key parameters: - name: slug in: path description: MCP server slug required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/InstallApiKeyReq' required: true responses: '200': description: The server, installed with a sealed API key content: application/json: schema: $ref: '#/components/schemas/InstallApiKeyResp' '400': description: Empty key, wrong credential_model, bad scope, or failed probe '404': description: No active server with that slug security: - bearer_pat: - admin - oauth2: - admin components: schemas: InstallApiKeyReq: type: object required: - api_key properties: api_key: type: string description: |- The bearer token the agent will use against the MCP backend. Caller is responsible for choosing the right scoping (e.g. Stripe restricted key `rk_test_...`, GitHub PAT, etc.). The platform doesn't validate the token shape - only its presence. scope: type: - string - 'null' description: |- `"team"` (default) - credential is shared across the workspace and used for every caller. `"user"` - credential is private to the caller; the resolver only uses it when *this* user is the one making the call (otherwise falls through to the team row if any). Server validates against `mcp_servers.allowed_scopes` and rejects scopes the operator hasn't permitted for this MCP. InstallApiKeyResp: type: object required: - slug - enabled - credential_ref - scope properties: credential_ref: type: string format: uuid enabled: type: boolean scope: type: string description: |- Echoed `team` / `user` so the caller can confirm the platform honoured their choice rather than silently defaulting. slug: type: string securitySchemes: bearer_pat: type: http scheme: bearer bearerFormat: hq_pat description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.' oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://app.hq.zone/v1/oauth/authorize tokenUrl: https://api.hq.zone/v1/oauth/token refreshUrl: https://api.hq.zone/v1/oauth/token scopes: admin: Administer the workspace (users, settings, integrations) agents:read: View the agents in your workspace agents:write: Create and configure agents billing:read: View usage and billing information conversations:read: Read your conversations and their messages conversations:write: Start conversations and send messages on your behalf documents:read: Read your documents library documents:write: Upload and manage documents in your library memory:read: Read what the assistant remembers about you memory:write: Correct or delete what the assistant remembers schedules:read: View your scheduled tasks schedules:write: Create and manage scheduled tasks tables:read: Read your tables and their rows tables:write: Create tables and add, edit, or delete rows ````