> For the complete documentation index, see [llms.txt](https://www.cakewalk.security/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.cakewalk.security/docs/ai-agent-access/how-to-guides/connections/add-a-custom-connection.md). # Add a Custom Connection Add an MCP server that is not in Cakewalk's catalog, so your Agents access it through the MCP Gateway under the same Policies. Most Connections come from the catalog. When the MCP server you want is not there (an internal server your team built, or a vendor Cakewalk has not cataloged yet) an Admin adds it as a custom Connection by entering its URL and how users authenticate to it. Once saved it behaves like any other Connection: it appears in [All Connections](/docs/ai-agent-access/how-to-guides/connections/all-connections.md), employees connect to it from My Connections, and [Policies](/docs/ai-agent-access/how-to-guides/policies.md) evaluate every tool call against it. *** ### 📖 Key concepts * **Custom Connection**: A Connection an Admin creates by hand rather than picking from the catalog. * **Connection type**: How employees authenticate to the MCP server. Four options, described below. * **App**: In companies that also run Human Access, every custom Connection attaches to an app your company already manages there. :bulb: *Why this matters*: A custom Connection puts an uncataloged MCP server under the same gateway, the same Policies and the same Audit Log as everything else. Without it, that server sits outside governance entirely. *** ### 🔐 Connection types Pick the one the MCP server supports. The form asks for credentials only where the type needs them. | Connection type | What employees do | You supply | | ------------------------------------------ | ---------------------------------------------------- | ----------------------------------------------------------- | | **OAuth with dynamic client registration** | Sign in through OAuth. | Nothing. Cakewalk registers the OAuth client automatically. | | **Token** | Connect with a personal token from the MCP provider. | Nothing. | | **OAuth with client ID** | Sign in through OAuth. | **Client ID**. | | **OAuth with client ID and secret** | Sign in through OAuth. | **Client ID** and **Client secret**. | Credentials are encrypted in your browser before they reach Cakewalk. *** ### 🌐 Cakewalk's gateway URLs The two client ID types need an OAuth client that you register with the MCP provider first. That registration asks where Cakewalk's gateway lives. Use these values. | What the provider asks for | Value | | ------------------------------------------ | --------------------------------------------------------- | | Base URL, app URL or homepage URL | `https://mcp-gateway.getcakewalk.io` | | Callback URL, redirect URI or redirect URL | `https://mcp-gateway.getcakewalk.io/api/v1/Auth/Callback` | Field names vary by provider. Match on what the field does, not what it is called. You come back with a Client ID, plus a Client secret if the provider issues one, and enter those in the form below. {% hint style="warning" %} Copy the callback URL exactly, capitalization included. Providers compare redirect URIs character by character, so a changed capital or an extra trailing slash fails at the consent screen rather than at save time. {% endhint %} The other two Connection types skip this. **OAuth with dynamic client registration** has Cakewalk register the client for you, and **Token** uses a personal token instead of an OAuth client. *** ### 🛠 Add a custom Connection **Navigation**: Connections → **Add org connection** → **Custom connection**. Which form opens depends on whether your company also runs Human Access. You will see one of the two below, not both. #### If your company runs Agent Access only {% stepper %} {% step %} #### Start a new org connection Open **Connections** and click **Add org connection**. {% endstep %} {% step %} #### Select Custom connection {% endstep %} {% step %} #### Fill in the required fields **Name**, **MCP Url**, **Product URL**, **Connection type** and at least one entry under **Categories**. {% endstep %} {% step %} #### Add credentials if the Connection type calls for them **Client ID** and **Client secret**. {% endstep %} {% step %} #### Pick the User groups, if Connection access is Curated Choose at least one group under **User groups**. Only Members of those groups can add this Connection. The field is absent while Connection access is set to Open. {% endstep %} {% step %} #### Add any optional detail Logo, **Certifications**, **Server locations**, **Tagline**, **Description**, **AI risk level** and **AI risk description**. {% endstep %} {% step %} #### Click Save {% endstep %} {% endstepper %} #### If your company also runs Human Access {% stepper %} {% step %} #### Start a new org connection Open **Connections** and click **Add org connection**. {% endstep %} {% step %} #### Select Custom connection Labelled "Connect your own MCP server to a cataloged app". {% endstep %} {% step %} #### Choose the App this MCP server belongs to The picker lists the apps your company manages in Human Access, and it is the only thing the form shows until you pick one. A custom Connection cannot exist on its own here: it always attaches to an app that already exists in Human Access. {% endstep %} {% step %} #### Check what Cakewalk filled in for you The rest of the form appears. Cakewalk takes the logo, **Product URL**, **Certifications**, **Server locations**, **Tagline** and **Description** from that app and locks them. To change any of them, change the app in Human Access. {% endstep %} {% step %} #### Fill in the fields that stay yours **Name**, **MCP Url** and **Connection type**, plus **Client ID** and **Client secret** if the type calls for them. {% endstep %} {% step %} #### Check Categories Cakewalk copies the app's category when a matching one exists. Otherwise pick at least one. {% endstep %} {% step %} #### Pick the User groups, if Connection access is Curated Choose at least one group under **User groups**. Only Members of those groups can add this Connection. The field is absent while Connection access is set to Open. {% endstep %} {% step %} #### Click Save {% endstep %} {% endstepper %} {% hint style="info" %} Attaching the Connection to an app keeps one record of that vendor across both modules, so access granted in Human Access and tool calls governed in Agent Access describe the same thing. If the app you need is not in the picker, add it in Human Access first. {% endhint %} {% hint style="warning" %} Changing the **App** after you have started filling the form clears what you entered and reloads the locked fields from the new app. Pick the app first. {% endhint %} *** ### 📋 Fields | Field | Required | Notes | | ----------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **App** | Yes, in companies running Human Access | The app in Human Access this MCP server belongs to. Not shown, and not needed, in companies running Agent Access only. | | Logo | No | Uploaded image. Taken from the app when one is attached. | | **Name** | Yes | What employees see in the catalog and on their Connection list. | | **MCP Url** | Yes | The MCP server endpoint Cakewalk's gateway calls. | | **Product URL** | Yes | The vendor or product homepage. Taken from the app when one is attached. | | **Connection type** | Yes | See the table above. | | **Client ID** | Only for the two client ID types | From the OAuth client you registered with the provider. Encrypted before it leaves your browser. | | **Client secret** | Only for **OAuth with client ID and secret** | From the same registration. Encrypted before it leaves your browser. | | **Categories** | Yes, at least one | Also usable as a Policy condition. | | **User groups** | Yes, while [Connection access](/docs/ai-agent-access/how-to-guides/connection-access.md) is Curated | The groups allowed to use this Connection. Not shown while Connection access is Open. | | **Certifications** | No | Policy condition. Taken from the app when one is attached. | | **Server locations** | No | Policy condition. Taken from the app when one is attached. | | **Tagline** | No | Short line shown with the Connection. | | **Description** | No | Longer description. | | **AI risk level** | No | Low risk, Medium risk or High risk. | | **AI risk description** | No | Why you gave it that level. | *** ### ✅ After you save * The Connection appears in [All Connections](/docs/ai-agent-access/how-to-guides/connections/all-connections.md) and in the catalog employees pick from. Under Curated Connection access, only Members of the groups you picked see it there. * Tools are discovered the first time an employee connects, then show on the Connection's **Tools** tab with their Action type. * Default and Custom [Policies](/docs/ai-agent-access/how-to-guides/policies.md) evaluate calls against it from the first tool call. * To change it later, open the Connection and choose **Edit custom connection**. Leave **Client ID** and **Client secret** blank to keep the stored credentials. *** ### 🔗 Related pages * [All Connections](/docs/ai-agent-access/how-to-guides/connections/all-connections.md) * [My Connections](/docs/ai-agent-access/how-to-guides/connections/my-connections.md) * [Connection Access](/docs/ai-agent-access/how-to-guides/connection-access.md) * [Agent Connections](/docs/ai-agent-access/connections-and-integrations/agent-connections.md) * [Policies](/docs/ai-agent-access/how-to-guides/policies.md) * [The MCP Gateway](/docs/ai-agent-access/concepts/the-mcp-gateway.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://www.cakewalk.security/docs/ai-agent-access/how-to-guides/connections/add-a-custom-connection.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.