Configure, test, and prepare for production

Once your custom MCP server can register and execute tools, configure it in your MCP client.

For a local stdio server, your client configuration may look like this:

{
  "mcpServers": {
    "contentstack-custom": {
      "command": "npm",
      "args": ["run", "dev"],
      "env": {
        "CONTENTSTACK_REGION": "NA",
        "CONTENTSTACK_API_KEY": "your_stack_api_key",
        "CONTENTSTACK_DELIVERY_TOKEN": "your_delivery_token"
      }
    }
  }
}

For a compiled production-style server:

{
  "mcpServers": {
    "contentstack-custom": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "CONTENTSTACK_REGION": "NA",
        "CONTENTSTACK_API_KEY": "your_stack_api_key"
      }
    }
  }
}

Do not commit real tokens to your repository or shared MCP configuration files.

Test with a read-only tool first

Start with a read-only CDA tool, such as listing assets.

Ask your MCP client:

List the first 10 assets in my Contentstack stack.

Then check:

• Did the MCP client discover the tool?

• Did the tool receive the expected arguments?

• Did your server resolve the correct region?

• Did your server attach the correct authentication headers?

• Did your server call the correct Contentstack API URL?

• Did your server return useful JSON or a readable result?

Once read-only tools work, test one write-capable tool in a development stack.

For example, if you expose a CMA entry creation tool, a tool call like this:

{
  "content_type_uid": "blog_post",
  "locale": "en-us",
  "branch": "main",
  "entry_data": {
    "entry": {
      "title": "Hello from MCP"
    }
  }
}

Should produce a request like this:

POST https://api.contentstack.io/v3/content_types/blog_post/entries?locale=en-us
api_key: <stack api key>
authorization: <management token>
branch: main
content-type: application/json

{
  "entry": {
    "title": "Hello from MCP"
  }
}

Add guardrails for write tools

AI agents can call tools quickly. Before exposing create, update, publish, unpublish, or delete tools, add guardrails.

Recommended guardrails:

• allowlist tools instead of exposing every tool by default

• separate read-only and write-capable server configurations

• require approval before write operations

• log every tool call with arguments, target stack, region, and result status

• block destructive operations in production

• restrict production writes to specific users or workflows

• redact tokens and secrets from logs

• return clear errors when credentials or required arguments are missing

A simple helper can flag write methods:

const writeMethods = new Set(["POST", "PUT", "DELETE"]);

function requiresApproval(definition: ContentstackToolDefinition) {
  return writeMethods.has(definition.mapper.method);
}

Some MCP clients already show tool approval prompts, but your server can still add its own policy layer.

Troubleshooting

The tool does not appear in the MCP client

Check that the MCP server starts without errors. Make sure your tool registration code runs before the server connects to the transport.

The API request goes to the wrong host

Check CONTENTSTACK_REGION and your regional base URL resolver. Contentstack APIs are regional, so the same tool may call different hosts depending on the organization region.

CDA tools return authentication errors

Check that you are sending both:

api_key
access_token

The access token should be a delivery token for the target stack and environment.

CMA tools return authentication errors

Check that you are sending:

api_key
authorization

For management-token authentication, authorization should be the management token.

For OAuth, check that your bearer token is valid and has the required scopes.

OAuth works locally but fails for another organization

Check region handling, organization context, and OAuth scopes. Make sure requests are sent to the correct regional endpoint for the authorized organization.

Write tools work in development but not production

Check stack permissions, branch permissions, workflow rules, publish rules, and token scopes. Also check whether your server blocks production write operations by policy.

Production checklist

Before using your custom Contentstack MCP server in production, confirm that you have:

• selected only the tool groups you need

• allowlisted specific tools

• separated read-only and write-capable workflows

• implemented OAuth if users should authorize access through Developer Hub

• stored tokens securely

• implemented token refresh for OAuth

• resolved Contentstack regional endpoints correctly

• added structured logging

• redacted secrets from logs

• added approval gates for write operations

• tested against a development stack

• documented which tools are available and why

Next steps

After the basic server works, you can extend it with:

• per-user OAuth sessions

• organization and stack selection

• branch-aware tools

• environment-aware read and publish workflows

• custom prompts for common content operations

• audit logging for all tool calls

• approval queues for publishing or deleting content

• internal tools that combine Contentstack with your own systems

A custom MCP server gives you the same basic building blocks as the official Contentstack MCP server, but with your own policies, workflows, and infrastructure around it.