> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.deepmask.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom MCP Server

> Connect any MCP-compatible server to DeepMask using an API key, a consumer key and secret, or a full OAuth 2.0 flow.

The **Custom MCP server** connector lets you bring any server that speaks the Model Context Protocol into DeepMask — an internal service, a vendor-hosted MCP, or something you built yourself. DeepMask discovers the server's tools at connect time and makes them available to the AI in your chats and projects.

Unlike the ready-made connectors, you supply the server URL and decide how DeepMask should authenticate to it.

<Info>
  Looking for a connector that is already wired up for you? See [MCP connectors](/features/mcp-connectors) for the full list of supported integrations.
</Info>

***

## Authentication options

When you add a Custom MCP server, an **Authentication** selector appears above the credential fields. Pick the option that matches how your server expects to be called.

<CardGroup cols={3}>
  <Card title="API Key" icon="key">
    A token DeepMask sends as a standard bearer credential. Also the right choice for servers that need no authentication at all.
  </Card>

  <Card title="Key & Secret" icon="id-card">
    A consumer key and secret forwarded to your server as headers, for servers that run their own OAuth against an upstream API.
  </Card>

  <Card title="OAuth 2.0" icon="shield-check">
    DeepMask runs the full OAuth 2.0 flow against endpoints you supply and refreshes tokens for you.
  </Card>
</CardGroup>

The selector changes which fields the form asks for. The **Name**, **Server URL**, and **System Prompt** fields are the same in all three modes.

<Note>
  The three modes are mutually exclusive. Switching an existing connector from one mode to another clears the credentials stored for the mode you left.
</Note>

***

## Option 1 — API Key

Use this when your server accepts a static token, or when it is open and needs no credential at all.

### Fields

| Field | Required | Notes |
| - | - | - |
| **Name** | Yes | How the connector appears in your connectors list. |
| **Server URL** | Yes | Your MCP endpoint, for example `https://your-mcp-server.com/mcp`. |
| **API Key / Token** | No | Leave blank for servers that do not require a credential. |
| **System Prompt** | No | Extra instructions the AI receives whenever it uses this connector's tools. |

### Steps

<Steps>
  <Step title="Open the connector form">
    Go to **Connectors**, click **Add connector**, and choose **Custom MCP server**.
  </Step>

  <Step title="Keep Authentication set to API Key">
    This is the default mode.
  </Step>

  <Step title="Enter the server URL and token">
    Paste your MCP endpoint. Add an API key or token only if your server requires one.
  </Step>

  <Step title="Test the connection">
    Click **Test Connection**. DeepMask calls your server and reports how many tools it discovered.
  </Step>

  <Step title="Save">
    Click **Add Connector**. The connector becomes available in your chats.
  </Step>
</Steps>

***

## Option 2 — Key & Secret

Some MCP servers run their own OAuth against an upstream API (a Salesforce-style MCP is the common case) and only need your application's credentials to do it. In that setup DeepMask does not perform any OAuth itself — it forwards your credentials to the server on every request and lets the server handle the rest.

### What DeepMask sends

| Field | Required | Header sent to your server |
| - | - | - |
| **Consumer Key** | Yes | `X-Consumer-Key` |
| **Consumer Secret** | No | `X-Consumer-Secret` |

Both values are encrypted at rest. Some servers only need the key, which is why the secret is optional.

### Steps

<Steps>
  <Step title="Choose Key & Secret">
    In the **Authentication** selector, click **Key & Secret**.
  </Step>

  <Step title="Enter your server URL">
    Paste the MCP endpoint your server exposes.
  </Step>

  <Step title="Paste the consumer key and secret">
    Use the credentials from the application registration your MCP server expects — for example the Consumer Key and Consumer Secret of a Salesforce External Client App.
  </Step>

  <Step title="Test and save">
    Click **Test Connection**, then **Add Connector**. The test sends the same headers the connector will use at runtime, so a pass here means your server accepted the credentials.
  </Step>
</Steps>

<Tip>
  Not sure whether your server wants **Key & Secret** or **OAuth 2.0**? If the server asks you for client credentials and handles the sign-in itself, use **Key & Secret**. If the server expects an access token on the `Authorization` header and points you at an authorization and token endpoint, use **OAuth 2.0**.
</Tip>

***

## Option 3 — OAuth 2.0

Choose this when your MCP server is protected by OAuth 2.0 and expects a bearer access token. DeepMask runs the Authorization Code flow with PKCE, stores the resulting tokens encrypted, and refreshes them automatically so you do not have to sign in again.

Nothing is baked in for a specific vendor — you supply every endpoint, so this works for any OAuth-protected MCP server.

### Before you start

Register an OAuth application with your identity provider and set its redirect URI to:

```
https://chat.deepmask.io/api/user/connectors/oauth/callback
```

Enter it exactly, with no trailing slash. Then collect the client credentials, the authorization and token endpoints, and the scopes your server requires.

### Fields

| Field | Required | What to enter |
| - | - | - |
| **Name** | Yes | How the connector appears in your connectors list. |
| **Client ID** | Yes | The client or consumer ID from your OAuth application registration. |
| **Client Secret** | Yes | The client secret. Stored encrypted and used server-side only. |
| **Authorization URL** | Yes | The endpoint you are redirected to for sign-in, for example `https://auth.example.com/oauth2/authorize`. |
| **Token URL** | Yes | The endpoint used to exchange the code and refresh tokens, for example `https://auth.example.com/oauth2/token`. |
| **Scopes** | Yes | Space-separated scopes, for example `mcp_api refresh_token`. |
| **User info URL** | No | Only used to label the connection with the signed-in account. |
| **Server URL** | Yes | Your OAuth-protected MCP endpoint. |
| **System Prompt** | No | Extra instructions the AI receives when using this connector's tools. |

<Warning>
  Include an offline or refresh scope (such as `refresh_token` or `offline_access`) in **Scopes**. Without one, your provider will not issue a refresh token and the connection stops working as soon as the first access token expires.
</Warning>

### Steps

<Steps>
  <Step title="Choose OAuth 2.0">
    In the **Authentication** selector, click **OAuth 2.0**. The form switches to the OAuth credential fields.
  </Step>

  <Step title="Fill in the credentials and endpoints">
    Enter the client ID and secret, the authorization and token URLs, and your scopes. Add the user info URL only if you want the connection labelled with the signed-in account.
  </Step>

  <Step title="Enter the MCP server URL">
    This is your MCP endpoint, not an OAuth endpoint.
  </Step>

  <Step title="Continue to the review screen">
    Click **Next**. DeepMask shows what happens during the redirect and which permissions are requested before sending you anywhere.
  </Step>

  <Step title="Authorize">
    Click **Continue**. You are taken to your provider's sign-in page. Approve the requested scopes.
  </Step>

  <Step title="Confirm">
    You return to DeepMask automatically and the connector shows as connected.
  </Step>
</Steps>

<Info>
  Access follows exactly the scopes you entered. DeepMask does not narrow them to read-only, so request only what your server actually needs.
</Info>

***

## Server URL requirements

The same rules apply to the MCP server URL and to the OAuth endpoints:

* The URL must use `http://` or `https://`.
* OAuth endpoints must use `https://`.
* Hosts that resolve to private or internal addresses are rejected, including `localhost`, loopback addresses, and private IP ranges. Your MCP server must be reachable from the public internet.

***

## Connection options and the system prompt

Both are optional and available in every authentication mode.

* **Connection options** — when the connector type declares configurable features, they appear as a **Connection options** section where you choose what to enable.
* **System Prompt** — free-text instructions attached to this connector. The AI receives them whenever it uses the connector's tools, which is a good place to describe when the tools should be used or what conventions your server expects.

***

## Testing before you save

For the **API Key** and **Key & Secret** modes, DeepMask requires a successful **Test Connection** before the **Add Connector** button is enabled. A successful test reports the number of tools discovered on your server.

The test is tied to the values currently in the form. Changing the URL, the credentials, the authentication mode, or any connection option clears the result and you have to test again.

OAuth connectors skip this gate — your provider's consent screen is the test.

***

## Editing a connector later

Open **Connectors**, select the connector, and choose **Edit**.

* **Secrets are never pre-filled.** The API key, consumer key, and consumer secret fields start empty. Leave a field blank to keep the stored value, or type a new value to replace it.
* **Switching modes clears the other side.** Moving from API Key to Key & Secret removes the stored API key, and moving back removes the stored consumer credentials.
* **OAuth connectors show Reconnect instead of Test Connection.** Reconnect reuses the credentials and endpoints already on file, so you do not re-enter them — you only sign in again. You re-enter credentials only if you delete the connection and start over.

<Note>
  The authentication mode cannot be switched between OAuth and the non-OAuth modes on an existing connector. To move an API Key connector to OAuth, add a new connector and remove the old one.
</Note>

***

## Troubleshooting

### Test Connection fails with an authorization error

**Cause:** The server rejected the credential DeepMask sent.

**Resolution:** Confirm you picked the right authentication mode. An API key sent to a server expecting `X-Consumer-Key` headers will fail, and so will the reverse. Check the token has not expired or been revoked.

***

### "Internal or private IP addresses are not allowed"

**Cause:** The server URL or an OAuth endpoint resolves to a private, loopback, or link-local address.

**Resolution:** Expose the server on a publicly resolvable hostname. DeepMask cannot reach services that are only addressable inside your network.

***

### "OAuth endpoints must use HTTPS"

**Cause:** The authorization or token URL was entered with `http://`.

**Resolution:** Use the `https://` form of both endpoints.

***

### OAuth sign-in fails with an invalid scope or redirect error

**Cause:** The scopes you entered are not all granted by your OAuth application, or the registered redirect URI does not match.

**Resolution:** Confirm the application grants every scope you listed, and that its redirect URI is exactly `https://chat.deepmask.io/api/user/connectors/oauth/callback` with no trailing slash.

***

### The connector worked but now asks for re-authorization

**Cause:** The refresh token expired or was revoked, or no refresh token was issued because the scopes did not include an offline or refresh scope.

**Resolution:** Open the connector and click **Reconnect**. If this keeps happening, add an offline or refresh scope to your OAuth application and to the connector's **Scopes** field.

***

### Tools do not appear after connecting

**Cause:** The server connected but exposed no tools, or the tool list changed after connecting.

**Resolution:** Run **Test Connection** again and check the reported tool count. If it is zero, confirm your server responds to the MCP `tools/list` request.

***

## Security and privacy

<Info>
  API keys, consumer credentials, OAuth client secrets, and tokens are encrypted at rest. DeepMask never shows a stored secret back to you — editing a connector always starts with empty credential fields.
</Info>

<Warning>
  A Custom MCP server is a connection you control. DeepMask cannot audit what your server does with a request, so connect only servers you trust and grant only the scopes they need.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.