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

# Custom MCP Servers

> Connect any remote MCP server by URL, with token, header, or OAuth 2.0 authentication.

A **custom MCP server** connects your workflows to any remote MCP (Model Context Protocol) endpoint that Spojit doesn't ship a built-in connector for. Point Spojit at a third-party hosted server, or at one your own team runs, and its tools become available to workflows just like any first-party connector.

Reach for a custom server when the service you need isn't in the catalog and the [HTTP Requests](/connectors/utilities/http) connector is too low-level: a custom server gives you typed, discoverable tools plus the same Agent Mode and Direct Mode behaviour as any other connector.

<Note>
  The server must be a remote endpoint that speaks **Streamable HTTP** MCP (for example `https://api.example.com/mcp`). Spojit discovers the tool list live from the server, so it always reflects the server's current state.
</Note>

## Add a custom server

<Steps>
  <Step title="Open the Connections page">
    Go to **Connections** and click **Add custom server** (next to **Add Connection**).
  </Step>

  <Step title="Enter the basics">
    * **Name**: a label to identify this server, for example `Internal CRM MCP`.
    * **Server URL**: the full MCP endpoint, for example `https://api.example.com/mcp`.
    * **Icon URL** (optional): an `https://` image URL to show as the connection's icon.
  </Step>

  <Step title="Choose an authentication mode">
    Pick **None**, **Token**, or **OAuth 2.0** depending on what the server requires. See [Authentication modes](#authentication-modes) below.
  </Step>

  <Step title="Set visibility and save">
    Choose **Organization** (all members can see and use it) or **Private** (only you and admins). Click **Save**. The server appears under **My Connections**.
  </Step>
</Steps>

## Authentication modes

Custom servers support three modes. Check the server's own documentation for which one it expects.

### None

For public servers, or servers that authenticate at the network boundary (VPN, mutual TLS). Some servers accept a key directly in the URL query string, in which case no separate credential is needed.

### Token (header)

Spojit sends a token on a header with every request. In the dialog, turn on **Requires authentication** and set:

* **Token**: the secret value, stored securely (never shown again after saving).
* **Header name**: default `Authorization`.
* **Prefix**: default `Bearer`.

The default sends `Authorization: Bearer <token>`. For an API-key header such as `X-API-Key`, set the header name and clear the prefix.

### OAuth 2.0 (bring your own app)

For servers backed by a standard OAuth provider, where an access token authorizes the server. You supply your own OAuth app's details:

<Steps>
  <Step title="Register the redirect URI on your OAuth app">
    Add this callback URL to your provider's OAuth app:

    ```
    https://miraxa.spojit.com/api/connectors/oauth/callback
    ```
  </Step>

  <Step title="Fill in the OAuth fields">
    Choose **OAuth 2.0** and enter the **Authorization URL**, **Token URL**, **Client ID**, **Client Secret**, and **Scopes**. Under **Advanced** you can toggle PKCE and switch client authentication between POST body and Basic header.
  </Step>

  <Step title="Save and authorize">
    Click **Save**. Spojit redirects you to the provider to consent, then stores the tokens and marks the connection **Connected**. Access tokens refresh automatically.
  </Step>
</Steps>

<Tip>
  Changing scopes (or the OAuth app) after connecting does not re-issue the token. Save your changes, then use **Reconnect** on the connection to re-authorize with the new scopes.
</Tip>

## Use a custom server in a workflow

Once the connection exists, add it to a workflow:

<Steps>
  <Step title="Add a Connector node">
    Drag a **Connector** node onto the canvas and open **Select Connector**.
  </Step>

  <Step title="Pick it under Custom Servers">
    Custom servers appear in their own **Custom Servers** section at the top of the picker. Select yours.
  </Step>

  <Step title="Choose tools and mode">
    Spojit discovers the server's tools live. Use **Agent Mode** to let the AI choose tools, or **Direct Mode** to call a specific tool. Optionally narrow the tool list under **Available Tools**.
  </Step>
</Steps>

## Edit or reconnect

Use the **Configure** button on the connection to change the name, URL, icon, or auth. For a token connection, leave the token blank to keep the current one; for OAuth, leave the client secret blank to keep it, or enter a new one to rotate it. Use **Reconnect** to re-run the OAuth flow after changing scopes or credentials.

## Caveats

* **Reachable from Spojit**: the server URL must be reachable from Spojit's runtime, not just your machine. Internal-only servers need a VPN or reverse proxy.
* **Secrets are stored securely**: tokens, client secrets, and OAuth tokens are stored securely and never shown after saving.
* **You own the OAuth app**: for OAuth mode you create and manage the OAuth application; Spojit only stores the credentials you supply.
* **Icons are https only**: the optional Icon URL must be an `https://` image URL.
* **Tenant-scoped**: a custom server is visible only within your organization. Its visibility (Organization or Private) controls who inside the tenant can see and use it.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot reach server">
    Confirm the URL is correct and reachable from Spojit's runtime. Check that the server is running and responding on the Streamable HTTP MCP endpoint.
  </Accordion>

  <Accordion title="Authentication failed">
    Verify the token is current and the header name matches what the server expects (for example `Authorization` versus `X-API-Key`). For OAuth, confirm the redirect URI is registered with the provider and the scopes are correct.
  </Accordion>

  <Accordion title="No tools appear">
    Confirm the endpoint is an MCP server that returns a tool list. Re-saving the connection re-runs tool discovery, so new tools on the server become available without recreating the connection.
  </Accordion>
</AccordionGroup>