Skip to main content
Our docs redesign is live!

How to build your own MCP server with Contentstack's tools API

•
2 min read
mcpapiaiautomationsecurity
tim-hero.png
AuthorTim Benniks

Contentstack provides an official MCP server that lets AI agents interact with Contentstack products through structured tools. For many use cases, the official server is the fastest way to get started.

However, there are situations where you may want to build your own MCP server instead.

You might want to:

  • expose only a small set of Contentstack tools

  • add custom approval flows before write operations

  • connect Contentstack tools with your own internal APIs

  • add logging, monitoring, or compliance checks

  • manage authentication in your own infrastructure

  • build a specialized MCP server for one stack, organization, or workflow

This guide shows you how to build a custom MCP server that uses Contentstack tool definitions.

The idea is simple:

  1. Fetch Contentstack tool definitions from public endpoints.

  2. Register those definitions as MCP tools.

  3. Let an MCP client call those tools.

  4. Convert each tool call into a Contentstack API request.

  5. Return the Contentstack API response to the MCP client.

The full flow looks like this:

MCP client
  -> calls a Contentstack tool
  -> your MCP server validates the tool arguments
  -> your MCP server reads the Contentstack tool mapper
  -> your MCP server builds a Contentstack REST or GraphQL request
  -> Contentstack returns a response
  -> your MCP server returns the result to the MCP client

By the end of this guide, you will have a working custom MCP server that can expose Contentstack tools to an AI client.

Prerequisites

Before you start, make sure you have:

  • Node.js 18 or later

  • a Contentstack account

  • access to a Contentstack stack

  • a stack API key, if your tools need stack-level access

  • a delivery token, if you want to use Content Delivery API tools

  • a management token or OAuth access, if you want to use Content Management API tools

  • an MCP-compatible client, such as Claude Desktop, Cursor, Claude Code, or another agent runtime

For OAuth-based workflows, you also need a Developer Hub app with OAuth configured.

Use OAuth when your MCP server should let users authorize access through Contentstack instead of relying on static tokens. You can create and configure the OAuth app in Developer Hub, where you define redirect URLs and the scopes your server needs.

Frequently asked questions

  • When should I build a custom MCP server instead of using Contentstack’s official server?

    Use a custom server when you need a smaller tool surface, custom approval flows, internal API integrations, added compliance controls, or custom auth handling.

  • How does the custom MCP server map MCP tool calls to Contentstack APIs?

    It fetches Contentstack tool definitions, registers them as MCP tools, validates arguments, then builds and executes the corresponding Contentstack REST or GraphQL request.

  • What do I need to run this guide’s MCP server implementation?

    You need Node.js 18+, a Contentstack account with stack access, and an MCP-compatible client such as Claude Desktop, Cursor, or Claude Code.

  • Which Contentstack credentials are required for different tool types?

    Delivery API tools typically require a delivery token. Management API tools require a management token or OAuth access; some tools may also require a stack API key.

  • When should I use OAuth instead of static tokens?

    Use OAuth when users should authorize access through Contentstack rather than relying on shared static tokens; you’ll need a Developer Hub app with redirect URLs and scopes configured.