Separate MCP Credentials by Environment

Prerequisites

Before configuring the MCP server, obtain the expected environment identifier for development and production. You also need access to enough Cloudinary product environments for the boundary you intend to create. Do not proceed with only a production environment and a plan to distinguish development assets by folder.

Decide which machines genuinely need more than one environment. A developer who works only in development has a different authentication requirement from a release machine that must reach both development and production.

Steps

1. Check whether the plan can support the boundary

   Count the product environments you need before creating client configurations. Reserve one for production, then account for development, staging, and any proposed developer-specific environments.

   Cloudinary caps product environments by plan. As shown on the pricing page on 2026-08-18, Free includes one product environment, Plus includes two, and Advanced includes three; Enterprise is custom, and the plan ladder continues beyond the publicly displayed tiers.

   The condition is concrete: Free cannot provide separate development and production environments. Plus can provide one of each, but no separate staging environment. Advanced can provide production plus two more environments. If one is shared staging, only one remains for development. An environment per developer therefore stops working above a small team unless the purchased plan supplies enough additional environments.

   For most teams within those caps, use shared development and production environments. Give a developer a personal environment only when the isolation is worth consuming one of the limited slots.

2. Put development outside the production product environment

   Create or select a development product environment that is distinct from production. A product environment is the isolation boundary. A folder named development inside the live product environment is only an organisational convention; it does not separate the credentials or the environment targeted by a tool call.

   This distinction matters for every operation exposed through the MCP server. Once a connection is authenticated to the production product environment, putting an asset under a development folder does not turn that connection into a development connection.

   Apply the same boundary to configuration. Create development configuration in the development product environment rather than treating a production folder as a substitute. In particular, manage upload preset configuration independently for the intended product environment. A familiar preset or folder name is not evidence that the connection points to the correct environment.

3. Use OAuth when a machine needs one environment at a time

   Configure separate remote connections for development and production, following the Cloudinary MCP server authentication documentation checked on 2026-08-18. Give each connection an unambiguous local name such as cloudinary-development or cloudinary-production; the name is an operator aid, not the safety check added later.

   Prefer OAuth for a developer workstation that should normally reach only development. OAuth binds a connection to one environment at a time. That makes accidental cross-environment writes harder than header authentication: the active connection cannot silently choose between several sets of environment credentials held by the same configuration.

   If production access is occasionally required, create a separate production connection and make switching an explicit action. Do not repurpose the development connection by changing its label while leaving its authentication state unclear. The detailed trade-off is covered in OAuth versus API key headers.

   OAuth does not remove the need for runtime verification. It reduces the number of environments a connection can address, but the user can still authenticate the wrong environment when establishing that connection.

4. Use header authentication only when one machine must hold several environments

   Header authentication is the only configuration in which one machine holds several environments at once. Use it when that capability is required, not merely because copying credentials appears convenient.

   This is also the configuration most likely to point at the wrong environment. Several valid credential sets exist on the same machine, and selecting the wrong set can still produce a successful authentication. Success proves that the credentials work; it does not prove that they address the environment intended for the current task.

   Create one complete, explicit profile per environment. Keep the expected environment identifier beside each profile, and require the caller to choose the profile by name. Do not create an unnamed shared default that can mean development in one command and production in another. Avoid copying a production profile to make development configuration unless every environment-specific value is replaced and then checked at runtime.

   Client configuration files are themselves an exposure and selection surface; account for that when deciding where MCP client credentials are stored. Separation means distinct credential sets and distinct profiles, not two labels referring to the same underlying values.

5. Make the first tool result prove the target environment

   Put a read-only call before the first operation that can create, update, or delete anything. Choose a call whose result includes the environment identifier. The Admin API reference is the source to consult when selecting the environment information returned by the operation.

   Compare that returned identifier with the expected identifier attached to the selected profile. Treat a missing identifier, an unexpected identifier, or an inability to perform the comparison as a failed precondition. Stop before the first write.

   The required sequence is:

   1. Select the named development or production profile.
   2. Load the expected environment identifier for that profile.
   3. Make the first read-only tool call.
   4. Extract the environment identifier from the tool result.
   5. Continue only when the returned and expected identifiers match exactly.

   This assertion is the check that catches a misconfiguration early. Do not trust the config file alone. A file can be named development while containing production credentials, and a copied profile can remain syntactically valid after the wrong values are inserted. The first tool result reflects the environment the server actually reached.

6. Apply the same assertion wherever the credentials run

   Put the identifier check in the execution path, not in a workstation-only setup note. A developer machine, release machine, and CI job can each have a correctly named profile containing the wrong credential set.

   For MCP-driven work in CI, require the expected environment identifier as an explicit job input or environment-specific value. Run the read-only call and comparison before the job performs a write. A production job must expect the production identifier; it must not infer production merely from a branch name, job name, or credential-file path.

   Header-authenticated automation deserves particular care because the same runner may hold credentials for several environments. Selecting a valid but incorrect profile will not necessarily fail authentication. The identifier mismatch must be what blocks the job.

Expected result

Development and production use distinct product environments and distinct authenticated connections. OAuth connections address one environment at a time; any machine that must hold several environments uses explicit header-authenticated profiles. Every execution reads the actual environment identifier before its first write and stops when that identifier does not exactly match the selected target.