Creating a key

1. 1Open your server in the dashboard and switch to the API Keys tab.
2. 2Click + New key and enter a label that identifies its purpose (e.g. production, staging, ci-tests).
3. 3Click Create. The raw key value is displayed once in an amber banner — copy it immediately.
4. 4Store the key securely (a secrets manager, environment variable, or vault). It is never shown again and is not recoverable.

Using the key

Pass the raw value in the X-API-Key header on requests to your server's auth endpoints. Always call these endpoints from your backend — never expose the key in client-side code.

POST /api/orgs/{orgId}/servers/{serverId}/auth/request-code
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "email": "user@example.com" }

After a user authenticates and receives a JWT, subsequent requests from their client use Authorization: Bearer {token} instead of the API key — the key stays on your server.

Key lifecycle

Each key in the list shows its label, creation date, and usage count. The available actions depend on whether the key has been used.

A key's usage count increments each time it is used to call request-code. Once a key has been used, deleting it is disabled to preserve audit history — archive it instead.

Archive vs. Delete

Archive (soft revoke)

Sets the key's status to revoked. The key record stays visible in the list so you know it existed and how many times it was used. Any active JWT that was issued using this key will fail the /auth/me revocation check immediately. New auth requests with the raw key value return 401.

Delete (hard delete)

Permanently removes the key from the database. Only available when usage count is 0 — meaning the key was created but never actually used to authenticate a request. Useful for cleaning up test keys or keys that were accidentally created.

Management endpoints

All management endpoints require a valid platform session token (your dashboard login) and admin role in the organization.

200 OK

{
  "keys": [
    {
      "keyId":      "abc123",
      "serverId":   "srv_xyz",
      "orgId":      "org_abc",
      "label":      "production",
      "status":     "active",
      "createdAt":  "2026-04-12T10:00:00.000Z",
      "usageCount": 42
    }
  ]
}

// Request
{ "label": "production" }

// Response — 201 Created
{
  "key": {
    "keyId":      "abc123",
    "label":      "production",
    "status":     "active",
    "createdAt":  "2026-04-12T10:00:00.000Z",
    "usageCount": 0
  },
  "rawValue": "aB3xK9..."   // shown once — store it now
}

// Response — 200 OK
{ "ok": true }

// Already archived — 409 Conflict
{ "error": "Key is already archived" }

// Response — 204 No Content (success)

// Has usages — 409 Conflict
{ "error": "Cannot delete a key that has been used. Archive it instead." }

Best practices

• Use one key per environment (production, staging, local). This limits blast radius if a key is compromised.
• Store keys in a secrets manager or environment variable — never hard-code them in source code or commit them to version control.
• Rotate keys periodically: create a new key, update your environment, then archive the old one.
• Archive rather than delete keys that have been used. The usage history is valuable for auditing.
• If a key is compromised, archive it immediately. All existing JWTs backed by that key are invalidated on the next /auth/me call.

Invoke endpoint

Every plugin shares the same URL pattern. Authentication uses your server's API key — the same credential you use for the auth service.

POST /api/orgs/{orgId}/servers/{serverId}/plugins/{pluginId}/invoke
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{ ...plugin-specific payload... }

Available plugins

Installation

1. 1In the Firebase Console, go to Project Settings → Service Accounts → Generate new private key. Download the JSON file.
2. 2In the MCPForDevs dashboard, open your server, go to the Plugins tab, and click Install on FCM Integration.
3. 3Paste the entire contents of the downloaded JSON file into the Service Account Key JSON field and click Install plugin.
4. 4The credential is stored encrypted in AWS Secrets Manager — it is never returned by the API in plain text.

Send to a single device

Pass registrationToken (string) to target one device. The response contains the FCM messageId assigned by Google.

POST /api/orgs/{orgId}/servers/{serverId}/plugins/fcm/invoke
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "registrationToken": "eAn3k7...",
  "title": "New message",
  "body": "You have a new notification",
  "data": {
    "screen": "inbox",
    "messageId": "msg_abc"
  }
}

200 OK

{
  "result": {
    "messageId": "projects/my-firebase-project/messages/0:1234567890123456%abc123"
  }
}

Send to multiple devices

Pass registrationTokens (array of strings) to fan out to up to 500 devices in a single call. The response includes per-token results so you can identify stale tokens.

POST /api/orgs/{orgId}/servers/{serverId}/plugins/fcm/invoke
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "registrationTokens": [
    "token-device-a",
    "token-device-b",
    "token-device-c"
  ],
  "title": "Flash sale",
  "body": "50% off — today only",
  "data": {
    "type": "promo",
    "promoId": "FLASH50"
  }
}

200 OK

{
  "result": {
    "successCount": 2,
    "failureCount": 1,
    "responses": [
      { "success": true,  "messageId": "projects/.../messages/abc" },
      { "success": true,  "messageId": "projects/.../messages/xyz" },
      { "success": false, "error": "registration-token-not-registered" }
    ]
  }
}

Request body reference

Either registrationToken or registrationTokens must be present — not both. Sending to a single token uses FCM's send() API; multiple tokens use sendEach().

Example — Node.js / fetch

const response = await fetch(
  `https://api.mcpfordevs.com/api/orgs/${ORG_ID}/servers/${SERVER_ID}/plugins/fcm/invoke`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.MCP_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      registrationTokens: userTokens,   // string[]
      title: "New notification",
      body: notificationBody,
      data: { type: "alert", id: alertId },
    }),
  }
);

const { result } = await response.json();

if (result.failureCount > 0) {
  const stale = result.responses
    .map((r, i) => (!r.success ? userTokens[i] : null))
    .filter(Boolean);
  await removeStaleTokens(stale);
}