Connect a client to MCP Profile Hub
Overview
Connect an AI client to MCP Profile Hub by adding a connector URL to the client: the public URL, or a profile's connector URL from the app. Each connection is a remote MCP server that the client reaches over Streamable HTTP, and it exposes the tools of one profile. On first connect, you sign in to Contentstack in the browser through Open Authorization (OAuth), so the client configuration contains no API keys, management tokens, or delivery tokens.
Tool calls run against live stack data with your own Contentstack roles. Because a profile can include create, update, delete, and publish tools, check what a profile exposes before you connect to it.
Use this when
- You want a scoped Contentstack toolset in an AI client, including web clients.
- You want everyone on a team to work with the same system profile.
Select an installation tab
The profile's Installation step shows six tabs, and each one generates a snippet for you to copy. The table below compares the six tabs:
| Tab | Transport | Needs Node.js | Config location | Notes |
|---|---|---|---|---|
| Claude Desktop | HTTP through the claude.ai connector | No | Your claude.ai account | Your Claude plan can limit who adds connectors |
| Claude Desktop Manual | stdio through the mcp-remote bridge | Yes | claude_desktop_config.json | Restart required after editing |
| Claude Code | HTTP, native | No | CLI-managed | Add --scope user to make the server available in every project |
| Codex | HTTP, native | No | ~/.codex/config.toml | |
| Cursor | HTTP, native | No | .cursor/mcp.json (project) or your global Cursor MCP config | Deeplink available |
| Generic | HTTP, native | No | Client-specific | Clients that support Streamable HTTP |
Prerequisites
- A connector URL. Use the public URL https://mcp-profile-hub.contentstack.com/api/mcp, which needs no Marketplace app, or a profile's connector URL from the Installation step in the app. See Create a profile.
- An MCP-compatible client. See Select an installation tab for the six clients with generated snippets, or another client that supports Streamable HTTP.
- For the Claude Desktop Manual path or any other stdio-only client, install Node.js to run the mcp-remote bridge. Without Node.js, the npx command fails and the server never starts.
- A Contentstack account whose roles already allow the operations the profile exposes. You can connect without those roles. However, a tool call fails at run time if your role does not permit it, because a profile never grants access beyond your existing roles. See About Product Roles for product-level access, and About Stack Roles for content tools.
Public URL sign-in
The public URL contains no profile, organization, or stack, so you select them during sign-in. Add the URL below to your client as a remote MCP server:
https://mcp-profile-hub.contentstack.com/api/mcp
On first connect, the client opens a browser and you complete the five steps below:
- Under Select your region, choose the region that hosts your organization, then click Continue to Contentstack. The regions are AWS North America, AWS Europe, AWS Australia, Azure North America, Azure Europe, GCP North America, and GCP Europe.
- Sign in to Contentstack and approve the requested access.
- Under Connect to Contentstack, confirm the Organization and select a Profile. The list shows the custom profiles you created under Your profiles, and system profiles under Standard profiles.
- If the profile's tools use a stack or a project, select them on the second step. The screen lists the stack, Launch, Personalize, Automate, Brand Kit, or Lytics fields that the profile uses, and marks each field as required or optional. For a profile whose tools use none of them, the screen skips this step.
- Click Connect.
The connection keeps your choices. MCP Profile Hub saves the stack and projects you select to your own configuration of that profile, and the app shows them. To switch to another profile or stack, use one of the two methods below:
- Set the new values in the connector URL parameters, for example profile_id for the profile and stack_api_key for the stack.
- Remove the server from your client and add it again, then select the new values at sign-in.
The region picker appears only when the URL does not identify your region. MCP Profile Hub skips it when the URL contains any of the values below:
- An org_uid of an organization that has signed in to MCP Profile Hub before. A profile's connector URL from the app contains it.
- A cma_host value.
- A region value.
The connect screen expires after 15 minutes. After that, close the browser window and start again from your AI client.
Client compatibility
MCP Profile Hub works with MCP clients that support Streamable HTTP, and with stdio clients through the mcp-remote bridge, but behavior differs between clients and models. A more capable model reads tool descriptions and input schemas more accurately, so it selects the correct tool and passes valid arguments more often. The table below lists the observed reliability of each client:
| Client | Reliability | Notes |
|---|---|---|
| Claude Code | Recommended | The most consistent connection and tool execution |
| Claude Desktop | Works | The connection can drop. Reconnect the server if tools do not appear |
| Claude on the web | Can be inconsistent | Your Claude organization's settings can require an administrator to enable and approve custom connectors |
| Codex | Depends on the model | Use a recent model. Older models select and call tools less reliably |
Connect
The first six sections below match the six installation tabs. The two Claude Desktop sections describe two ways to set up the same app, and Generic covers the other clients that support Streamable HTTP, including ChatGPT.
All examples use the asset_librarian profile, with the connector URL below:
https://mcp-profile-hub.contentstack.com/api/mcp?profile_id=asset_librarian&org_uid=<ORG_UID>
Replace the profile_id and organization UID with your own, or copy the ready-made snippet from the profile's Installation step. To connect with the public URL instead, use https://mcp-profile-hub.contentstack.com/api/mcp in place of the profile URL in any snippet below.
Each snippet names the server after the profile, replacing underscores with hyphens: the profile content_explorer becomes the server content-explorer.
Claude Desktop (claude.ai connector)
The Claude Desktop tab adds the profile as a connector to your claude.ai account, not to the desktop application's config file. Claude on the web and the Claude desktop app both use connectors from that account. To configure the desktop application's own config file, use Claude Desktop Manual below.
To add the connector from the app, open the profile's Installation step and click Add to Claude on the Claude Desktop tab. The button opens claude.ai with the connector name and URL filled in, and you confirm them to add the connector.
If your Claude plan limits custom connectors to organization admins, the button adds the connector only for an organization admin. Other users can use the Claude Desktop Manual tab instead, or ask a Claude organization admin to add the connector. For more information, refer to Profile Hub Client Setup.
To add the connector manually, follow the three steps below:
- In your claude.ai settings, add a custom connector with a name, for example Asset Librarian, and the connector URL.
- Complete the Contentstack OAuth sign-in in the browser.
- Start a new conversation. The profile's tools are available in it.
Claude Desktop Manual
Configure the Claude Desktop app through claude_desktop_config.json using the mcp-remote bridge. This setup requires Node.js, as Prerequisites states.
The snippet on the Installation step contains the exact mcp-remote version that Contentstack currently pins, so copy the snippet rather than typing it. For the reason Contentstack pins the version, see Pinned mcp-remote version.
The block goes inside mcpServers and has the shape below, where <PINNED_VERSION> is the version the Installation step shows:
{
"mcpServers": {
"asset-librarian": {
"command": "npx",
"args": [
"-y",
"mcp-remote@<PINNED_VERSION>",
"https://mcp-profile-hub.contentstack.com/api/mcp?profile_id=asset_librarian&org_uid=<ORG_UID>"
]
}
}
}Restart after editing. Claude Desktop reads claude_desktop_config.json only at launch, so until you restart it the server does not appear and Claude Desktop shows no error. Restart Claude Desktop.
Sign in on first use. On first use, a browser opens for Contentstack OAuth.
Claude Code
Claude Code supports remote HTTP MCP servers natively. Add the profile with the command below:
claude mcp add --transport http asset-librarian "https://mcp-profile-hub.contentstack.com/api/mcp?profile_id=asset_librarian&org_uid=<ORG_UID>"
Without quotes around the URL, the shell reads ? and & as shell syntax rather than as part of the URL, and the command fails. Keep the URL in quotes.
To make the server available in every project, add --scope user, as the command below shows:
claude mcp add --transport http --scope user asset-librarian "https://mcp-profile-hub.contentstack.com/api/mcp?profile_id=asset_librarian&org_uid=<ORG_UID>"
Then start sign-in from Claude Code, for example with the /mcp command, and complete the Contentstack sign-in in the browser.
Codex
Add the section below to ~/.codex/config.toml, one [mcp_servers.<name>] block per profile:
[mcp_servers.asset-librarian] url = "https://mcp-profile-hub.contentstack.com/api/mcp?profile_id=asset_librarian&org_uid=<ORG_UID>"
On first use of a tool, Codex runs the browser OAuth flow.
Cursor
The Cursor tab has an Add to Cursor button that opens Cursor and adds the profile as an MCP server.
To add it manually, add the server under mcpServers in .cursor/mcp.json (project level) or your global Cursor MCP config, as the snippet below shows:
{
"mcpServers": {
"asset-librarian": {
"url": "https://mcp-profile-hub.contentstack.com/api/mcp?profile_id=asset_librarian&org_uid=<ORG_UID>"
}
}
}Reload Cursor so it reads the new configuration. On first tool use, Cursor opens a browser for Contentstack OAuth.
Generic (other MCP clients)
MCP clients that support Streamable HTTP connect directly. Add the connector URL from the Generic tab to the client as a remote HTTP MCP server. On the first call, the client discovers the authorization endpoints and signs you in over OAuth.
A manually added Authorization header replaces the OAuth handshake, so the server rejects the call. Do not add bearer tokens or API keys.
ChatGPT
ChatGPT connects to remote MCP servers as custom connectors, and your ChatGPT plan determines whether custom connectors are available. To connect a profile, follow the three steps below:
- In ChatGPT, add a custom connector with a name and the connector URL.
- Complete the Contentstack OAuth sign-in and approve the scopes.
- Enable the connector in a conversation, then ask ChatGPT to perform a task that the profile's tools cover.
stdio-only clients
For a client that supports only stdio, connect through the mcp-remote bridge with the same config shape that the Claude Desktop Manual section shows.
Verify
The client lists the connected server and its tools once authorization completes. The list below shows where each client lists them:
- Claude Code: the /mcp command lists the server as connected.
- Claude Desktop and Claude on the web: the profile's tools appear in the conversation's tool list.
- Cursor: Cursor's MCP settings list the server as connected.
- Codex and other clients: the profile's tools appear in the client's tool list.
Then ask the agent to perform a task the profile's tools cover, for example with the prompt below:
List the assets in my stack.
If no tools appear, or a call fails, refer to the Troubleshooting section.
Authentication and permissions
MCP Profile Hub authenticates you through standard OAuth. You do not create, share, or rotate an API key to sign in.
How a client authenticates
The diagram below shows which component acts at each stage of the sign-in:
MCP client --connect--> MCP Profile Hub MCP Profile Hub --sign-in required--> MCP client MCP client: 1. Discover the authorization endpoints 2. Register through Dynamic Client Registration 3. Open a browser for OAuth 2.1 with PKCE Browser: 1. Select your region, if the URL does not set it 2. Sign in to Contentstack and approve the requested scopes 3. Select the profile and its stack or projects, if the URL does not specify a profile MCP client: 1. Receive an access token and a refresh token 2. Cache both tokens locally 3. Refresh the access token automatically
The four steps below describe each stage:
- The client connects to the connector URL, and the server responds that the client must sign in.
- It discovers the authorization endpoints automatically and runs OAuth 2.1 with Proof Key for Code Exchange (PKCE). It registers itself through Dynamic Client Registration, so you configure no client ID and no client secret.
- A browser opens. You select your region if the URL does not set it, sign in to Contentstack, and approve the requested scopes. If the URL does not specify a profile, you then select the profile and its stack or projects.
- The client receives an access token and a refresh token, caches them locally, and refreshes the access token automatically.
Scopes derive from tools
Contentstack derives the OAuth scopes a profile requests from the tools it exposes. A read-only profile requests only read scopes, and a profile with a publishing tool also requests the scope needed to publish. You approve the concrete set in the browser at connect time.
When you add tools to a profile, it can therefore request more scopes. Connected users approve the new ones the next time they sign in.
Permissions follow your roles
Because every call runs with your own Contentstack roles, the three rules below apply:
- You can perform only the operations your account already allows.
- A profile narrows what is available to the agent, and never grants access your roles do not already allow.
- A call that exceeds your permissions fails.
The table below answers common questions about sign-in and permissions:
| Question | Answer |
|---|---|
| Do I need to install the Marketplace app? | No. The public URL works without it. You need the app for tasks such as building custom profiles, saving configuration, or reviewing your tool calls in the Executions view |
| Is the connector URL sensitive? | No. The profile_id and org_uid values are identifiers, not secrets. A stack API key in the apikey parameter grants no access without your sign-in |
| Can a profile give someone extra access? | No. Each person connects with their own sign-in and their own roles |
| Can a teammate use my custom profile's URL? | No. A custom profile is available only to the person who created it. A teammate who connects with its URL gets a profile-not-found error. To give a teammate the same tools, export the profile and have them import it |
Pinned mcp-remote version
The generated snippets pin mcp-remote to a specific version instead of the latest release. Copy the version from the Installation step, which shows the version that Contentstack currently pins.
Because mcp-remote names its OAuth credential directory under ~/.mcp-auth/ after its own version, each new version reads a different directory. An unpinned npx -y mcp-remote command therefore reads an empty credential directory after each new mcp-remote release, and the client prompts you to authorize again.
When Contentstack updates the pinned version, the new version also reads an empty credential directory, so each user signs in again. After you sign in, the client reconnects.
Troubleshooting
Additional Resource: For more information on installation and sign-in errors, refer to the Profile Hub Client Setup section of the Contentstack MCP Troubleshooting Guides documentation.
Next Steps
- MCP URL parameters: configure values such as the stack, branch, or project from the connector URL.
- Profiles and catalogs: what a profile exposes.
- Authentication and permissions: the OAuth sign-in flow, and why a profile can never grant more access than your roles allow.
- Contentstack MCP Server: the locally installed alternative, which exposes the full toolset on one machine instead of a scoped hosted profile.