Skip to main content

Connect a private tool without putting its credential in prompts

Section: DOC-CP-secrets#manage-project-secrets.

Connect an agent to a private tool without copying its provider credential into a prompt or client application. Store the credential once, configure the approved integration to reference it, and exercise the tool before bringing it into use.

The public secrets API returns metadata rather than stored values. Keep your original credential in your own secure store so you can replace or recover it.

Prerequisites and availability​

Section: DOC-CP-secrets#prerequisites-and-availability.

Use a backend secret API key issued for your account and a deployment that exposes the Project Secret APIs. Keep the key and credential out of browser code, conversations, source control and diagnostic logs.

The current API does not enforce separate permissions for each secret operation. A key that can reach this API can manage the project's secrets. Treat that access as sensitive.

Store and reference a credential​

Section: DOC-CP-secrets#store-and-reference-a-credential.

Choose this recipe when a custom MCP server needs a provider credential. Obtain that credential from the service owner, decide which server may receive it, and keep a recoverable copy in your own secure store. Store the value once and give the connection only its secret name.

  1. Choose a unique project secret name using the name and value limits.
  2. Store the credential with put-secret. Retain its returned metadata and version; the response does not reveal the value.
  3. Configure the approved custom MCP connection to use that name as its secret reference. Check the destination before supplying it a credential.
  4. Test the connection and exercise the intended tool before declaring setup complete.

A secret's name is a reference, not an authorization grant. The credential reaches the destination when the integration uses it; only bind it to a destination you intend to trust.

Finish by exercising the intended tool through the configured connection. Success means the approved server can perform the permitted task; metadata alone proves only that a secret record exists. If authentication fails, inspect the reference and provider credential before writing another version.

Find the credential used by a failing connection​

Section: DOC-CP-secrets#inspect-and-list.

Read the connection’s secret metadata and page through the project’s secrets when investigating a missing credential. These reads do not return the credential value.

Replace a provider credential and verify the integration​

Section: DOC-CP-secrets#rotate-and-recover.

Writing an existing name replaces its value without editing each reference. After a confirmed change, inspect metadata and test the connection that uses it. If the write fails or times out, pause further rotation: the value and metadata may no longer agree. Keep the intended credential in your secure store, check its validity with the issuing service, and use the returned metadata and a connection test to investigate. If the active version remains unclear, ask your account contact to resolve it before overwriting a potentially newer value.

A request already holding the old credential may finish. Replacing the platform value does not revoke that credential at its issuer. During an incident, separately revoke the compromised credential with its provider and verify the replacement works.

Disconnect the tool before retiring its credential​

Section: DOC-CP-secrets#remove-a-credential.

Identify and change connections that use this secret, then verify the replacement path or deliberately disable dependent work. Delete the retired secret and separately revoke the old credential at its issuer. Inspect the deletion result; a submitted request does not prove cleanup completed.

Section: DOC-CP-secrets#related-reference.

Project Secret APIs gives the current request and response shapes. Authentication explains credentials and caller scope; custom MCP connections explains their use with tools. The OWASP secret lifecycle guidance covers rotation, revocation and recovery practices.

Document ID: DOC-CP-secrets. Section identities and revisions.