On-premises | Polytomic Docs

For on-premises (self-hosted) deployments, the Polytomic MCP server runs in your own environment at a URL your administrator chooses, such as https://mcp.polytomic.mycompany.com/mcp. Everything in Getting started applies, with your server’s URL in place of https://mcp.polytomic.com/mcp.

Choose how to connect

How you connect depends on where your MCP server can be reached from:

Remote connector with OAuth sign-in: your MCP server is reachable from the MCP client. You add the server’s URL as a remote connector and sign in to Polytomic.
Polytomic Connector with an API key: your MCP server is only reachable from within your network, for example a private-cloud or VPN-gated deployment. A Claude Desktop extension on your machine bridges Claude Desktop to the server.

Follow the steps for your client in Getting started, using your MCP server’s URL.

Restricted OAuth sign-in

Your administrator can limit which MCP clients may sign in with OAuth, or turn OAuth sign-in off. If sign-in is off, connect with an API key using the Polytomic Connector or manual configuration.

Administrators can find the settings in MCP OAuth clients.

Connect with the Polytomic Connector

The Polytomic Connector is a Claude Desktop extension that bridges Claude Desktop to your on-premises Polytomic MCP server. It runs on your machine, where the MCP server is reachable, and authenticates with a Polytomic API key.

Connector prerequisites

Claude Desktop, with the Polytomic Connector extension installed (see below).
The URL of your Polytomic MCP server, e.g. https://mcp.polytomic.mycompany.com. Your MCP server must be reachable from the machine running Claude Desktop.
A Polytomic API key. Create one in Polytomic under Settings → API keys.

Private and internal certificates

The connector loads your operating system’s trust store at startup, so an MCP server secured with an internal or private certificate authority is verified automatically.

Install the connector

Download the latest version of the connector (polytomic-connector.mcpb) from the connector releases on GitHub.
Double-click the file to open it in Claude Desktop.
Review the details, then click Install.

Installing the Polytomic Connector in Claude Desktop

Install dialog doesn't appear?

If double-clicking the file opens Claude Desktop but no install dialog appears, your organization may have disabled side-loaded extensions. Use manual configuration instead.

Configure the connector

Configuring the Polytomic Connector

After installing, click Configure and fill in the connection settings:

MCP server URL (required) — the full URL of your Polytomic MCP server, e.g. https://mcp.polytomic.mycompany.com.
Polytomic API key (required) — a Polytomic API key. Create one in Polytomic under Settings → API keys.
Read-only access (optional) — turn this on to restrict the connection to read-only Polytomic operations. Leave it off for full access.

Click Save.

Read-only mode

When read-only access is enabled, the connector tells the MCP server to allow only read operations. Use this when you want Claude to explore and report on your Polytomic deployment without making changes.

Enable the connection

Enabling the Polytomic Connector

After configuring the extension click the Enabled toggle to connect. You can change the settings any time by clicking Configure, or remove the connector with Uninstall.

Start a new chat in Claude Desktop and ask about your Polytomic deployment to confirm the connection is working.

Configure manually (without the connector extension)

If you can’t install the connector extension — for example, your organization disables side-loaded Claude Desktop extensions — you can configure the same connection by hand. This bridges Claude Desktop to your on-premises MCP server over stdio using mcp-remote, exactly as the connector does internally.

When to use manual configuration

The connector extension is the recommended path. Use manual configuration only when you can’t install the extension. The result is the same: Claude Desktop connects to your on-premises MCP server with your Polytomic API key.

Manual configuration prerequisites

Node.js installed on your machine. The manual bridge runs via npx, and Claude Desktop does not provide a node or npx you can use for this — it spawns whatever is on your system PATH.
The URL of your Polytomic MCP server and a Polytomic API key, as in the Connector prerequisites above.

Edit the Claude Desktop config

Open Claude Desktop’s configuration file (claude_desktop_config.json):
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
You can also reach it from Settings → Developer → Edit Config.

Add a polytomic entry under mcpServers, replacing the URL and API key with your own:

{
  "mcpServers": {
    "polytomic": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.polytomic.mycompany.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:Bearer ${POLYTOMIC_API_KEY}"
      ],
      "env": {
        "POLYTOMIC_API_KEY": "<your-api-key>"
      }
    }
  }
}

The server URL must include the /mcp path. To restrict the connection to read-only Polytomic operations, add "--header", "X-Polytomic-Access-Mode:read-only" to the args array.

Save the file and fully restart Claude Desktop.

Start a new chat and ask about your Polytomic deployment to confirm the connection is working.

Internal or private certificates

Unlike the connector extension, the manual bridge runs as its own Node.js process, so it does not automatically load your OS trust store. If your MCP server uses an internal or private certificate authority, point Node at your CA bundle by adding "NODE_EXTRA_CA_CERTS": "/path/to/your-ca.pem" to the env block (or "NODE_OPTIONS": "--use-system-ca" on Node 22+ to use the system trust store).

Troubleshooting

Cannot reach the MCP server — with the Polytomic Connector, confirm the machine running Claude Desktop can reach the MCP server URL (for example, that you are on the VPN). The connector runs on your machine, so the server only needs to be reachable from there, not from Anthropic. With a remote connector in Claude’s hosted apps, the MCP server and your Polytomic URL must be reachable from Anthropic, as described in Connect with OAuth sign-in.
Authentication errors — verify the API key is valid and has not been revoked. Create a new key in Polytomic under Settings → API keys if needed.
Certificate errors — the connector trusts your OS certificate store. If verification fails, ensure your internal certificate authority is installed in your operating system’s trust store. With manual configuration, set NODE_EXTRA_CA_CERTS instead, as described above.
npx or node not found (manual setup) — install Node.js on your machine and restart Claude Desktop so it can launch the bridge.
“This OAuth client isn’t allowed on this Polytomic deployment.” — your administrator has restricted which MCP clients may sign in. Ask them which clients are allowed, or connect with an API key using the Polytomic Connector.