Your AI agent can work with your content.
Login
← All articles

Connect Your AI Agent to Your Content Workspace with Decoupla MCP

October 4, 2026

Dumitru Postolachi

Dumitru Postolachi

Connect Your AI Agent to Your Content Workspace with Decoupla MCP

You can now connect your own compatible AI agent to your Decoupla content workspace through MCP, with access scoped to one project and permissions you choose.

That means an editorial assistant can work with drafts, a content workflow can prepare structured entries for your website, or an agent can inspect your content model before proposing changes. You decide which operations each connection can access, and you can revoke that access when you need to.

What MCP brings to Decoupla

MCP stands for Model Context Protocol. It gives compatible AI agents a standard way to discover and use tools provided by a service. In Decoupla, those tools let an agent work with your content types, entries, and media.

We integrated the MCP service into the Contenthive backend repository and deployed it as a separate service, available through Decoupla at:

https://mcp.decoupla.com/mcp

The connector provides tools and access. Your connected agent decides how to use those tools based on your instructions and the permissions you grant. Connecting an agent does not, by itself, start creating or publishing content.

Work with structured content using your own agent

Depending on its connection's permissions, an agent can:

  • Discover content types, inspect their fields, and understand supported filters.
  • Read published content and, when permitted, draft content.
  • Create or update entries as drafts.
  • Create or update published entries.
  • Create or modify content types and their fields.
  • Delete content types or fields when explicitly permitted.
  • Upload media.
  • Generate images when explicitly permitted.

These capabilities give you building blocks for workflows that fit your team. For example, you could ask a compatible editorial agent to inspect your article fields and save a new article as a draft for review. Or you could use an agent to update existing content, prepare structured content for a website, or upload assets.

An agent inspecting your project can learn the content model before working with entries. Entry listing also supports cursor pagination, so agents can work through larger collections in bounded pages.

These are examples of workflows you can build with a compatible agent. The connector supplies the tools; the agent's capabilities, your instructions, and the granted permissions determine what happens.

Connect an agent in five steps

Before you begin, check that your agent client supports remote MCP over Streamable HTTP and custom authorization headers. Configuration formats vary between clients, so follow your client's setup instructions.

  1. In Decoupla, open Project → API Settings → Agent connections.
  2. Create a named connection, such as Editorial assistant.
  3. Choose the permissions the agent needs. New connections default to reading published content.
  4. Copy the token immediately. It is displayed only when the connection is created.
  5. Add the MCP endpoint and token to your agent's configuration.

For clients that support the following configuration format, an example is:

{
  "mcpServers": {
    "contenthive": {
      "url": "https://mcp.decoupla.com/mcp",
      "headers": {
        "Authorization": "Bearer <AGENT_TOKEN>"
      }
    }
  }
}

Replace <AGENT_TOKEN> with the token you copied. No separate project identifier is required: the connection token identifies the project.

For an editorial workflow, choose the permissions needed to read the relevant content and write drafts. Add publishing, content-model changes, or image generation only when your workflow needs them.

Set up popular AI clients

Choose the instructions for the client you use. These examples cover OpenAI Codex, Anthropic Claude Code, Google Gemini CLI, and Cursor. A provider's chat app can have different connection options from its agent client.

Create your Decoupla agent connection first, then replace <AGENT_TOKEN> with that connection's token. Use a separate named connection for each client if you want to track and revoke its access independently. Keep tokens out of shared configuration files and source control.

The examples below follow the clients' documented configuration formats. They are setup guidance, rather than a claim that every client version has been tested with Decoupla.

OpenAI: Codex CLI

Add this section to your personal ~/.codex/config.toml:

[mcp_servers.decoupla]
url = "https://mcp.decoupla.com/mcp"
bearer_token_env_var = "DECOUPLA_AGENT_TOKEN"

Set DECOUPLA_AGENT_TOKEN in the environment where you launch Codex. For example, in a macOS or Linux terminal:

export DECOUPLA_AGENT_TOKEN='<AGENT_TOKEN>'
codex

The variable contains the token alone; Codex sends it as a bearer token in the authorization header. In Codex CLI, use /mcp to inspect active servers. This uses the direct MCP configuration path. Decoupla's ChatGPT plugin connection flow still requires the OAuth integration described below. See the official OpenAI MCP documentation.

Anthropic: Claude Code

With Claude Code installed, run:

claude mcp add --transport http decoupla https://mcp.decoupla.com/mcp --header "Authorization: Bearer <AGENT_TOKEN>"

This adds a connection available to you in the current project by default. Start Claude Code and use /mcp to check the connection status and available tools. Decoupla uses the token you supplied, so no OAuth sign-in is needed for this setup. See the Claude Code MCP documentation.

Google: Gemini CLI

With Gemini CLI installed, run:

gemini mcp add --transport http --header "Authorization: Bearer <AGENT_TOKEN>" decoupla https://mcp.decoupla.com/mcp

Run gemini mcp list to inspect the configured servers and connection status. If you configure Gemini CLI through settings.json instead, use httpUrl for the endpoint and headers for authorization. In Gemini CLI, url selects SSE, while httpUrl selects Streamable HTTP. See the Gemini CLI MCP documentation.

Cursor

For a personal connection, add the following to ~/.cursor/mcp.json. If the file already contains servers, merge the decoupla entry into its existing mcpServers object.

{
  "mcpServers": {
    "decoupla": {
      "url": "https://mcp.decoupla.com/mcp",
      "headers": {
        "Authorization": "Bearer <AGENT_TOKEN>"
      }
    }
  }
}

Save the file and restart Cursor. Use Agent to work with the available MCP tools. See the Cursor MCP setup documentation.

Check your first connection

Start with a request such as: “Inspect this project's content types and explain their fields without changing anything.” The agent can only use tools permitted by its Decoupla connection.

If the server does not connect, check the endpoint, the authorization header, and whether the token is still valid. If a tool is missing, check the connection's permissions in Project → API Settings → Agent connections.

Connect from desktop apps

Desktop connection options depend on the app version and your workspace settings. Create a Decoupla agent connection first and use its token in the setup below.

Claude Desktop

Claude supports account-based remote MCP connectors in its desktop app. Where the custom connector and request-header options are available:

  1. Open Customize → Connectors in Claude, then + Add → Add custom connector.
  2. Name it Decoupla and enter https://mcp.decoupla.com/mcp. Select Continue.
  3. Review the detected authentication settings. For Decoupla's token-based connection, select No sign in.
  4. Under Request headers, add a header named Authorization with the value Bearer <AGENT_TOKEN>.
  5. Select Add. In a conversation, open + → Connectors and enable Decoupla.

“No sign in” skips OAuth; the authorization header still authenticates the connection. On Team and Enterprise plans, an owner may need to add the connector, and its fixed credential is shared by people using that connector. Choose permissions appropriate for that audience.

These remote connectors connect from Anthropic's infrastructure, even when you use the desktop app. See Claude's official custom connector instructions.

ChatGPT desktop: direct MCP on a local Codex host

OpenAI documents direct MCP connections for desktop sessions using a local Codex host. Where Settings → MCP servers is available:

  1. Select Add server, name it Decoupla, choose Streamable HTTP, and enter https://mcp.decoupla.com/mcp.
  2. Configure the bearer token in the host's personal ~/.codex/config.toml. Merge these settings into the existing Decoupla server section:
[mcp_servers.decoupla]
url = "https://mcp.decoupla.com/mcp"
http_headers = { Authorization = "Bearer <AGENT_TOKEN>" }
  1. Save and restart the desktop app. Use /mcp to inspect connected servers.

Keep this personal file private: the example stores your token directly. You can instead use the environment-variable configuration shown in the Codex CLI section, provided the desktop process can access that variable.

This applies to local Codex-host MCP configuration. Decoupla's ChatGPT plugin connection flow is not available yet; it requires additional OAuth support. See OpenAI's official desktop MCP documentation.

Keep control over each connection

Each customer connection is bound to one project and has its own permissions. You manage those connections in Project → API Settings → Agent connections.

Permissions are enforced by both the backend and the MCP service. Tools unavailable to a connection are hidden from its tool list, and unauthorized calls are rejected.

You can see usage and last activity in the frontend and revoke a connection. Revocation blocks subsequent requests, although an operation already in progress may finish.

Connection tokens are stored as hashes. Private upstream API credentials are not shown to customers.

Reading content or writing drafts does not automatically grant image generation. Image generation requires both explicit image-generation permission and media-upload permission.

Current usage limits

The current default limits are:

  • 60 permitted tool requests per connection per minute.
  • 25 image-generation attempts per project per UTC day, shared across MCP connections and legacy MCP API keys. Failed upstream generation attempts also count.
  • 20 MB per media upload.

These limits apply to the connector's usage. An LLM subscription should not be assumed to include image-generation costs.

Available today—and what requires OAuth support

Decoupla's MCP integration is deployed and working for clients that support remote MCP over Streamable HTTP with custom authorization headers. Support depends on the client; every AI agent does not necessarily support this connection method.

OAuth sign-in is not implemented yet. You cannot currently connect this integration directly through ChatGPT's plugin connection flow. That connection path requires an additional OAuth integration.

For now, use a compatible client that lets you configure the remote endpoint and bearer token.

Start with one focused workflow

Open Project → API Settings → Agent connections, create a connection for your compatible agent, and choose the permissions for the task you want it to handle.

Whether you want to draft articles, update structured entries, or understand your content model, Decoupla's MCP integration gives your agent a way to work directly in your content workspace—with project-specific permissions and revocable access.