Add authentication and OAuth

Tool definitions do not include credentials. Your MCP server must add authentication when it executes the API request.

For local development, use environment variables:

CONTENTSTACK_REGION=NA
CONTENTSTACK_API_KEY=your_stack_api_key
CONTENTSTACK_DELIVERY_TOKEN=your_delivery_token
CONTENTSTACK_MANAGEMENT_TOKEN=your_management_token
CONTENTSTACK_OAUTH_ACCESS_TOKEN=your_oauth_access_token

Create src/auth.ts:

export function getAuthHeaders(group: string) {
  const apiKey = process.env.CONTENTSTACK_API_KEY;
  const deliveryToken = process.env.CONTENTSTACK_DELIVERY_TOKEN;
  const managementToken = process.env.CONTENTSTACK_MANAGEMENT_TOKEN;
  const oauthAccessToken = process.env.CONTENTSTACK_OAUTH_ACCESS_TOKEN;

  if (group === "cda") {
    if (!apiKey || !deliveryToken) {
      throw new Error(
        "CDA tools require CONTENTSTACK_API_KEY and CONTENTSTACK_DELIVERY_TOKEN"
      );
    }

    return {
      api_key: apiKey,
      access_token: deliveryToken
    };
  }

  if ((group === "cma" || group === "cma-extended") && managementToken) {
    if (!apiKey) {
      throw new Error("CMA tools require CONTENTSTACK_API_KEY");
    }

    return {
      api_key: apiKey,
      authorization: managementToken
    };
  }

  if (oauthAccessToken) {
    return {
      ...(apiKey ? { api_key: apiKey } : {}),
      authorization: `Bearer ${oauthAccessToken}`
    };
  }

  throw new Error(`No authentication configured for group "${group}"`);
}

CDA authentication

For Content Delivery API tools, send:

api_key: <stack api key>
access_token: <delivery token>

Use this for read-only access to published content.

CMA authentication with a management token

For Content Management API tools, you can use a management token.

Send:

api_key: <stack api key>
authorization: <management token>

This is useful for stack-scoped server-to-server workflows.

OAuth authentication with Developer Hub

Use OAuth when users should authorize your MCP server through Contentstack instead of sharing static tokens.

See https://www.contentstack.com/docs/developer-hub/contentstack-oauth for more info.

OAuth is a good choice when:

• you are building a reusable integration

• multiple users or organizations need to authorize access

• users should be able to install or revoke the integration

• you need scoped permissions

• you are working with Developer Hub, Launch, Analytics, BrandKit, or Personalize tools

• actions should happen on behalf of a user

To use OAuth, create an app in Developer Hub and configure OAuth for that app.

At a high level:

1. Open Developer Hub.

2. Create or select your app.

3. Open the OAuth configuration.

4. Add one or more redirect URLs.

5. Choose the scopes your MCP server needs.

6. Save the app configuration.

7. Implement the OAuth authorization flow in your MCP server.

8. Store the access token and refresh token securely.

9. Attach the bearer token when executing OAuth-backed Contentstack tools.

Your MCP server should request the smallest useful set of scopes. For example, do not request broad write permissions if the server only needs to read entries or inspect configuration.

For OAuth-backed requests, your auth helper should attach the bearer token:

authorization: Bearer <oauth access token>

Depending on the tool group, you may also need stack, organization, project, or product-specific headers.

Examples:

A production OAuth implementation should also handle token refresh, token expiration, revoked access, and secure token storage.