What is MCP Profile Hub?
Overview
MCP Profile Hub connects your AI client to Contentstack through one hosted Model Context Protocol (MCP) URL, and limits each connection to the tools of one profile. A profile is a fixed set of Contentstack tools for one job, for example the Asset Librarian profile for organizing the asset library. You connect clients that support Streamable HTTP directly, and stdio clients through the mcp-remote bridge.
Ways to connect
You connect to MCP Profile Hub in one of the two ways below:
- Public URL: you add https://mcp-profile-hub.contentstack.com/api/mcp to your MCP client, and choose the region, profile, and stack or project in the browser during sign-in. This path needs no Marketplace app. At sign-in, you select a system profile or one of your own custom profiles.
- Marketplace app: you install the MCP Profile Hub app to build custom profiles and save a profile's configuration. The app also provides ready-made client snippets and the Executions view of your tool calls.
What a profile exposes
A profile exposes a fixed subset of Contentstack tools.
Because a large toolset lowers a model's accuracy in selecting the correct tool, a profile exposes only the tools you select. A large toolset also uses more of the context window and can cause smaller models to fail on common workflows.
After you connect a profile, your AI agent can run tasks such as the examples below:
- Look up entries, assets, and publish status in plain language.
- Publish or update content in the environments your role permits.
- Move entries through workflow stages and request publish approval.
- Inspect content models and generate implementation guidance.
- Run your own Contentstack Automate automations and Agent OS agents as single tool calls.
Profile properties
Every profile has the three properties below:
- Scoped: the client receives only the tools that the profile exposes.
- Contextual: tool definitions include values from your stack, for example content types, locales, branches, environments, taxonomies, and releases (see Stack-aware tool definitions).
- Governed: you sign in with Open Authorization (OAuth), each operation runs with your existing Contentstack roles, and the runtime records each tool call (see Execution logging).
Additional Resource: For more information on the OAuth sign-in, the scopes you approve, and the role permissions that apply to each tool call, refer to the Authentication and permissions documentation.
Audience
MCP Profile Hub serves the four groups below:
- Content editors who retrieve entries or run the operations their role permits without opening the CMS.
- Developers who call Contentstack tools from an IDE or terminal.
- Operations teams that run repeatable content and campaign workflows.
- Admins who build profiles with a limited set of tools for non-technical users.
Comparison with MCP Server
Both MCP Profile Hub and the Contentstack MCP Server connect AI agents to Contentstack and cover similar tasks. They differ in their installation method and in the number of tools they expose to your agent. The table below compares them.
| Contentstack MCP Server | MCP Profile Hub | |
|---|---|---|
| Installation | Runs locally through npx. You configure it per machine with a management or delivery token or an OAuth session | Contentstack hosts it at mcp-profile-hub.contentstack.com. You add the connector URL to your client. Clients that support Streamable HTTP need no local installation, and stdio-only clients need Node.js to run the mcp-remote bridge |
| Transport | stdio, so it works only in clients that can run a local process | Streamable HTTP, so it also works in web clients such as claude.ai and ChatGPT |
| Tool selection | Tool groups, for example cma and launch. Each group loads its full toolset | Curated per profile. Each profile exposes only the tools its job needs |
| Configuration | Environment variables on each machine | You choose it at sign-in, set it on the connector URL, or save it on the profile in the app |
The MCP Server gives a developer the full toolset on their own machine. MCP Profile Hub provides a scoped, hosted toolset that a team can share across MCP clients.
Setup and architecture
An MCP Profile Hub setup has three components:
- Profiles: Contentstack provides system profiles for common jobs, and you build custom profiles in the app.
- The hosted runtime at mcp-profile-hub.contentstack.com: it loads the profile, authenticates you, applies stack context, checks permissions, and runs operations.
- MCP clients: an MCP-compatible app, for example Claude, Claude Code, Cursor, Codex, or ChatGPT, that connects to a profile's connector URL.
You set this up in the two steps below:
- Choose a profile. Use a system profile, or create a custom profile in the app: select tools, configure a stack, and save. When you set no profile in the URL or at sign-in, the connection uses the cms system profile.
- Add a connector URL to your MCP client: the public URL, or the profile's URL from the app's Installation screen. The client opens a browser for Contentstack OAuth. You sign in, approve the requested scopes, and choose any region, profile, stack, or project that the URL does not set. To change the profile later, you reconnect.
The connector URL of a profile does not change when you edit the profile.
For a profile in the app, the Installation screen pre-fills the profile_id and org_uid values in the URL below, which you copy:
https://mcp-profile-hub.contentstack.com/api/mcp?profile_id=<PROFILE_ID>&org_uid=<ORG_UID>
The default connector URL contains no secrets.
Neither value in the URL above is a secret, because Contentstack identifies you through OAuth sign-in, not through a value in the URL. URL parameters are configuration, not credentials, as the three parameters below show:
- profile_id: identifies the profile that the connection uses.
- org_uid: points sign-in at your organization, and has no effect on a tool call.
- apikey: a stack API key in this parameter grants no access by itself, because every call runs with your own OAuth sign-in and roles.
Query parameters override the profile's saved configuration.
You can set values such as the stack, branch, or project of a shared system profile through query parameters in the connector URL. The saved profile in the app does not change.
Additional Resource: For more information on the query-string parameters that set values such as the stack, branch, environment, and project for a single connection, and the order in which Contentstack applies them, refer to the MCP URL parameters documentation.
Tool call flow
When your client calls a tool, the runtime handles it in the order below:
MCP client --tool call--> Runtime Runtime: 1. Validate token 2. Resolve stack 3. Apply context (branch, environment, locale) 4. Check role permissions 5. Execute against Contentstack 6. Log to Executions Runtime --result--> MCP client
Stack-aware tool definitions
When a client calls tools/list, the runtime reads your Contentstack setup and adds values from it to the tool definitions of the catalogs below:
- Content Management API (CMA) and Content Delivery API (CDA)
- Launch
- Brand Kit
- Personalize
- Developer Hub
For CMA tools, the added values include the content types, environments, locales, branches, taxonomies, releases, global fields, and workflows in your stack. A stack contains too many terms and assets to list, so a parameter that takes a term or an asset specifies the search tool that finds one instead.
An injected list limits the values the model sends. When a tool's branch parameter lists the existing branches as an enum, the model selects a value from that list. When the parameter has no enum, the tool call sends the model's value without validation.
Two caps apply to the injected values: an injected list stops at 50 entries, and tool definitions cache for five minutes. Limitations states both in full.
Lytics, Analytics, and Automate tools include no stack values. Their definitions stay the same for every connection.
Execution logging
MCP Profile Hub records every tool call. Each entry records the user, profile, tool, client (when the client identifies itself), status, timestamp, duration, and input parameters, plus the error message of a failed call. The runtime does not store the tool's result. The app's Executions view is a searchable history of those calls, and you use it to diagnose a failed call from its error message.
Click to enlarge
Limitations
- Injected lists cap at 50 values. A tool definition lists at most 50 values of each kind, for example content types, branches, or taxonomies. When your stack has more, the definition states the number of values it shows and specifies the tool that returns the full set.
- Tool definitions cache for five minutes. A change you make in Contentstack, such as a new branch, appears in the tool definitions only after the cached definitions expire.
- Executions shows only your own tool calls. To review activity across users, use the stack audit log.
Next Steps
- Create a profile: select tools, set stack context, and save a profile to get its connector URL.
- Connect a client to MCP Profile Hub: add the public URL or a profile's connector URL to your MCP client and complete OAuth.
- Profiles and catalogs: the catalogs that group the tools a profile can expose.
- Monitor tool calls: read the Executions view to confirm that tool calls reach Contentstack.
- Contentstack MCP Troubleshooting Guides: diagnose failed tool calls from their error messages.