Connections

What are Connections?

Connections represent the bridge between deco CMS and external MCP servers. A Connection is deco CMS’s registered relationship with an upstream MCP server—whether that’s GitHub, Slack, a database, or your custom MCP implementation.

Connecting to Upstream MCP Servers

Why Connections Exist

The Connection abstraction solves a critical problem: separating connection configuration from usage. Instead of every client (Cursor, Claude Desktop, custom agents) managing their own credentials and endpoints for each MCP server, deco CMS centralizes this once.

The Problem Without Connections

Without a centralized connection layer:

• Every client must store and manage credentials for every MCP server they use
• Credential rotation means updating every client
• No unified audit trail of which tools were accessed and by whom
• Authorization policies drift across different clients
• No way to temporarily revoke access to an MCP server without updating all clients

How Connections Solve This

Connections provide:

Centralized credential management: Store credentials once in deco CMS’s encrypted vault. Clients authenticate to deco CMS, not to individual MCP servers.

Unified authorization: Define who can access which tools through deco CMS’s permission system, rather than managing access per MCP server.

Credential rotation without client updates: Update credentials in deco CMS; all clients automatically use the new credentials without reconfiguration.

Complete observability: Every tool invocation flows through deco CMS, creating a unified audit trail across all MCP servers.

Secure credential handling: Credentials are encrypted at rest and only decrypted at request time, never exposed to clients.

Design Principles

1. Connections are Read-Only From Client Perspective

Clients interact with tools exposed by Connections, but they cannot modify the Connection configuration itself. This separation ensures:

• Credentials remain protected
• Configuration changes require appropriate authorization
• Audit trails remain trustworthy

2. Connections Compose Into Virtual MCPs

Connections are the building blocks for Virtual MCPs. You connect individual MCP servers (GitHub, Slack, databases), then compose them into Virtual MCPs that expose curated tool surfaces.

 GitHub Connection  ──┐
Slack Connection   ──┼──▶ Virtual MCP (Project) ──▶ Clients
Database Connection──┘ 

This composition model keeps external MCP servers isolated and secure while enabling flexible, dynamic tool surfaces through Virtual MCPs.

3. Connections are Organization-Scoped

All Connections belong to an organization. This scoping ensures:

• Clear tenant isolation
• Organization-wide credential management
• Consistent access policies across projects and agents

How Connections Work

When a client invokes a tool through deco CMS:

1. Client authenticates to deco CMS (OAuth or API key)
2. Authorization check: deco CMS verifies the client has permission to invoke the requested tool
3. Credential loading: deco CMS decrypts stored credentials for the target Connection
4. Request proxying: deco CMS forwards the MCP request to the upstream server with credentials
5. Monitoring: deco CMS logs the invocation (tool, duration, status, errors)
6. Response return: deco CMS returns the MCP server’s response to the client

This flow ensures credentials never leave deco CMS’s secure boundary while enabling seamless tool invocation.

Connection Types

Connections typically fall into three categories:

SaaS Integration MCPs: Services like GitHub, Slack, Notion, Google Drive—external systems with their own authentication (often OAuth).

Infrastructure MCPs: Database connections, Kubernetes clusters, cloud provider APIs—systems requiring sensitive credentials.

Custom MCPs: Your own MCP servers exposing domain-specific tools and operations.

All connection types follow the same pattern: register once in deco CMS, use everywhere through Virtual MCPs and agents.

Connections vs. Direct Access

Direct Access (client → MCP server):

• ✅ Simple for single-client, single-server scenarios
• ❌ Credentials managed per client
• ❌ No unified observability
• ❌ Authorization logic duplicated

Through Connections (client → deco CMS → MCP server):

• ✅ Centralized credential management
• ✅ Unified authorization and observability
• ✅ Credential rotation without client updates
• ✅ Foundation for Virtual MCPs and composition

For production usage, Connections provide the control plane capabilities needed to operate MCP traffic at scale.

Connecting MCP Clients to deco CMS

Once you’ve configured upstream connections, you need to connect your MCP clients (Cursor, Claude Desktop, custom agents) to deco CMS to consume the tools.

Client Authentication Options

There are two common ways to connect clients to deco CMS:

• OAuth (recommended for interactive clients): supports standard OAuth flows, consent, and organization-aware access.
• API Keys (recommended for servers/agents): scoped keys with explicit tool permissions.

Endpoints

Depending on your use case, you’ll connect to one of these endpoints:

• Management MCP: POST /mcp - Access deco CMS management tools (creating connections, projects, agents)
• Connection proxy: POST /mcp/:connectionId - Direct access to a specific upstream connection
• Agent (virtual server): POST /mcp/agent/:agentId - Access a curated tool surface through an agent

Authentication Quick Notes

• OAuth is ideal when you want per-user identity and browser-based sign-in.
• API keys are ideal for automation and server-to-server access (least friction to bootstrap).