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

# Custom MCP server: connect your own tools to Semji agents

> Bring your own MCP server, like a custom CMS bridge or an internal tool, and let Semji's AI agents use its tools via OAuth or an API key.

## At a glance

* **What you can do**: connect any MCP server you host, such as a bridge to a custom CMS, an internal tool, or a third-party service, and let Semji's AI agents use its tools.
* **Who it's for**: workspace owners and the developers who run the MCP server.
* **How it works**: you register the server once for the workspace, connect it with OAuth or an API key, then enable it on the AI agents that should use its tools.

Beyond the built-in CMS integrations, this is the way to plug in anything Semji doesn't cover natively.

## Requirements for your MCP server

* Served over HTTPS and reachable from the public internet. Servers on private networks cannot be connected.
* Speaks the MCP streamable HTTP transport.
* **If you use OAuth**, the server must implement the MCP authorization specification:
  * It advertises its protected-resource metadata (RFC 9728), either via a `WWW-Authenticate` header on unauthenticated requests or at `/.well-known/oauth-protected-resource`.
  * Its authorization server publishes standard discovery metadata (RFC 8414 or OpenID Connect discovery).
  * Its authorization server supports Dynamic Client Registration (RFC 7591). Semji registers itself automatically, manually pre-registered client IDs are not supported.
  * It accepts the redirect URI `https://app.semji.com/integrations/mcp/callback`.
* **If you use an API key**, the server must accept it as `Authorization: Bearer <key>` on every request.

You must also be a workspace owner in Semji to add a server.

## How to add your MCP server

<Steps>
  <Step title="Open the MCP integrations">
    In Semji, open Settings → Integrations, go to the MCP tab, and click Add server. You must be a workspace owner.
  </Step>

  <Step title="Describe the server">
    Fill in the form:

    * **Name**: a display name. Agents see it as the server's name.
    * **Description**: optional.
    * **URL**: the HTTPS URL of your MCP server, for example `https://mcp.example.com`. The URL cannot be changed after creation.
    * **Authentication method**: OAuth (sign in through the provider's consent screen) or API key (paste a token). With API key, paste it into the API key field.
  </Step>

  <Step title="Connect">
    Click Connect.

    * **OAuth**: a new tab opens on your provider's consent screen. Sign in and approve within 10 minutes.
    * **API key**: the key is stored immediately, without a live test against your server.

    Back on the MCP tab, the server row shows its status: Connected, Not connected, or Expired.
  </Step>

  <Step title="Enable it on your agents">
    Open the agent's configuration, go to Enhancements → Custom MCP Servers, and toggle your server on. The agent discovers the server's tools at run time.
  </Step>
</Steps>

<Note>
  Depending on your Semji configuration, connections are shared by the whole workspace or made per user ("Each team member connects their own account."). With per-user connections, each teammate connects from the MCP tab or from their profile settings. Agents silently skip servers the current user hasn't connected, and the chat shows "You are not connected to …. Connect it to let this agent use it."
</Note>

## Manage the server

From the MCP tab, each server row offers:

* **Connect / Disconnect**: manage the stored credentials.
* **Edit**: change the name and description. The URL is immutable, so to change it, delete the server and add it again.
* **Delete**: permanently removes the server from the workspace. Every connected member loses access.

## Firewalls and IP allowlisting

Your MCP server must be reachable from the public internet. Semji's own servers call it for connection and OAuth flows (discovery, client registration, token exchange).

Semji's servers reach the internet through a fixed set of outbound IP addresses. If a firewall, WAF, or anti-bot protection (Cloudflare, Akamai, Sucuri, …) sits in front of your site, it can block Semji's requests — typically with a `403 Forbidden` — before they ever reach your CMS, even when your credentials are correct.

Allow the following Semji IP addresses:

```text theme={null}
63.34.75.122
63.35.78.179
54.228.104.165
18.200.156.37
34.248.117.83
52.213.28.177
```

<Warning>
  Do not restrict access to your MCP server to the IP list above alone. AI agent tool calls run from Semji's AI provider infrastructure, whose addresses are not fixed. Rely on OAuth or the API key for authentication, and use the IP list to exempt Semji from WAF or anti-bot challenges, not as an exclusive allowlist.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="OAuth connection fails immediately">
    Semji discovers your server's OAuth configuration live. Frequent causes, surfaced with explicit error messages:

    * The server does not support Dynamic Client Registration (RFC 7591). Pre-registered clients are not supported.
    * The protected-resource metadata is missing or declares no authorization servers.
    * The authorization-server metadata lacks an `authorization_endpoint` or `token_endpoint`, or is not served over HTTPS.
    * Discovery requests time out (10-second limit per request).
  </Accordion>

  <Accordion title="The popup was blocked by your browser. Allow popups to connect to the MCP server.">
    Allow popups for the Semji app domain and connect again.
  </Accordion>

  <Accordion title="The status shows Expired">
    The server's authorization stopped accepting Semji's stored credentials (for OAuth, the refresh token was rejected). Click Connect to re-authenticate. API-key servers ask for the key again.
  </Accordion>

  <Accordion title="Agents don't see the server's tools">
    * The server isn't enabled on the agent (Enhancements → Custom MCP Servers).
    * The server isn't connected for the current user (per-user mode) or the workspace.
    * The API key is wrong. It is stored without a live test, so a bad key only surfaces at run time.
    * A firewall blocks tool calls (see the firewall section above).
  </Accordion>

  <Accordion title="An MCP server with URL … already exists in this workspace">
    Each URL can only be registered once per workspace. Reuse the existing server, or delete it first if you need to recreate it.
  </Accordion>
</AccordionGroup>

## Related

* [MCP: connect Claude or another AI assistant to Semji](/en/connect-your-tools/mcp): the reverse direction, use Semji's tools from Claude and other assistants.
* [CMS Publisher: publish your content to your CMS without leaving Semji](/en/connect-your-tools/cms-publisher)


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