Adding a Custom MCP Server

Connect any remote MCP server to Spojit by URL, with token, header, or OAuth authentication.

Overview

Spojit's built-in connector catalog covers the most common services, but the architecture is open: any remote server that speaks the Model Context Protocol can be added as a connector. Your team can build an internal MCP server for a proprietary system, point Spojit at a third-party hosted server, or self-host a community-published one, then use it in workflows alongside the built-in connectors.

Use a custom server when the service you need isn't in the catalog and the HTTP Requests connector is too low-level. A custom MCP server gives your workflows typed tools, structured outputs, and the same Direct Mode and Agent Mode ergonomics as any first-party connector.

What You Can Do

A custom server exposes whatever tools that specific server registers; each server defines its own catalog. Typical examples:

An internal CRM server exposing create-lead, update-opportunity, list-pipelines.
A proprietary ERP server exposing create-purchase-order, get-stock-level.
A hosted GitHub MCP server with list-pull-requests, create-issue, get-repo.
A team-owned reporting server with run-query, list-saved-reports.

Spojit discovers the exact tool list live from the server, so it always reflects the server's current state.

Before You Start

The server must be a remote endpoint that speaks Streamable HTTP MCP, for example https://api.example.com/mcp.
The URL must be reachable from Spojit's runtime, not just your machine. Internal-only servers need a VPN or reverse proxy.
Have any credentials ready: a token, or your OAuth app's client ID, client secret, and endpoints.

Adding the Connection

Custom servers use a dedicated dialog, not the connector catalog.

Go to Connections and click Add custom server (next to Add Connection).
Enter a Name to identify the server, for example Internal CRM MCP.
Enter the Server URL, the full MCP endpoint.
Optionally add an Icon URL. It must be an https:// image URL.
Choose an Authentication mode (see below).
Set Visibility: Organization (all members can see and use it) or Private (only you and admins).
Click Save. The server appears under My Connections.

Authentication Modes

Check the server's documentation for which mode it expects.

None: for public servers, servers that authenticate at the network boundary, or servers that accept a key directly in the URL.
Token: Spojit sends a token on a header with every request. Enter the Token, the Header name (default Authorization), and the 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 OAuth app for servers backed by a standard OAuth provider. See the next section.

Setting Up OAuth 2.0

With OAuth you supply your own OAuth application's details, and the access token authorizes the server.

In your OAuth provider, register Spojit's callback URL as the app's redirect URI: https://miraxa.spojit.com/api/connectors/oauth/callback. The dialog shows the exact URL with a copy button.
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.
Click Save. Spojit redirects you to the provider to consent, then stores the tokens and marks the connection Connected. Tokens refresh automatically.

Using It in a Workflow

Once the connection exists, add a Connector node and open Select Connector. Custom servers appear in their own Custom Servers section at the top of the picker. Select yours, then choose Direct Mode with a specific tool, or Agent Mode to let the AI decide. Tool inputs and outputs follow whatever schema the server declared.

Editing and Reconnecting

Use the Configure button on the connection to change its 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. If you change OAuth scopes or credentials, use Reconnect to re-run the authorization flow so the new scopes take effect.

Tips

For internal servers, deploy them behind your VPN or use mutual TLS so credentials don't have to leave your network.
Re-saving a connection re-runs tool discovery, so tools added to the server become available without recreating the connection.
Changing OAuth scopes does not re-issue the existing token; save, then Reconnect to apply them.
Use the HTTP Requests connector for genuinely one-off calls; build or connect a custom MCP server when you want typed, discoverable, reusable tools across many workflows.

Common Pitfalls

Connection refused: the server URL must be reachable from Spojit's runtime, not just your laptop. Internal-only URLs need a VPN or reverse proxy.
Authentication failed: confirm the token is current and the header name matches what the server expects. For OAuth, confirm the redirect URI is registered with the provider and the scopes are correct.
Schema drift: if the server changes a tool's input schema, workflows referencing the old schema can break. Version your endpoints if breaking changes are possible.
Slow first save: a server with many tools can take a few seconds to list on the first save; Spojit then reflects the tools when you use it in a workflow.

Common Use Cases

For technical API details and field specifications, see the Custom MCP Servers documentation.