Connecting AI agents to Faddom through MCP

Available from version 2026.2

Connect Claude Code, Codex CLI, or any other agent that supports MCP to the Faddom MCP server to ask questions about your infrastructure directly from your agent, such as how many servers you have or where a service lives. This works across Claude, GPT, and cloud hosting platforms such as AWS Bedrock. The MCP server runs inside your Faddom server, so nothing extra installs on the Faddom side.

Endpoint: https://<faddom-host>:9443/WebServices/api/v1/mcp/compass, where <faddom-host> is your Faddom server's address.
Protocol: MCP over HTTPS (stateless HTTP transport), exposing one tool: compass(prompt, conversationId, timezone).

This guide only changes settings on the agent machine, not on the Faddom server.

Prerequisites

Before you start, make sure you have all of the following.

#	Requirement	If you're missing this
1	Network access from the agent machine to the Faddom server on TCP 9443 (the same port the Faddom web UI uses)	Connection refused
3	An API Access Token for a user whose role has View permission for AI Chat	Step 1: Create an API token
4	A trusted, correctly-named TLS certificate on the Faddom server	TLS certificate errors
5	The Compass AI Module	Our Modules Overview

Step 1: Create an API token

In the Faddom UI, create an API Access Token for a user whose role has View permission for AI Chat. This permission is set under Settings > Access Control > Roles > Edit Role > Artificial Intelligence > AI Chat.
Save the token somewhere safe. Treat it like any other API key: it can be rotated or revoked in the UI at any time.

Step 2: Connect your agent

Connect Claude Code

Windows users: run this command in an elevated Command Prompt. PowerShell uses different syntax and processes it differently.

claude mcp add --transport http --scope user faddom \   https://<faddom-host>:9443/WebServices/api/v1/mcp/compass \   --header "Authorization: Bearer <token>"

Verify: run /mcp and confirm faddom ✓ connected appears.

Connect Codex CLI

codex mcp add faddom-mcp --transport http https://<faddom-host>:9443/WebServices/api/v1/mcp/compass --header "Authorization: Bearer <token>"

Verify: run codex mcp list and confirm faddom appears.

If either command connects cleanly, you're done. If you instead see something like ERR_TLS_CERT_ALTNAME_INVALID or a certificate/hostname error, that's expected against Faddom's default certificate. Head to TLS certificate errors below.

Troubleshooting

TLS certificate errors

You'll see this as ERR_TLS_CERT_ALTNAME_INVALID, a hostname mismatch, or a self-signed certificate warning when you run the connect commands in Step 2.

Why it happens: your agent checks two things before connecting: whether a certificate authority it trusts signed the certificate, and whether the address you connect to appears in the certificate's Subject Alternative Name (SAN). Faddom's default certificate is self-signed with no usable SAN, so a direct connection fails verification out of the box.

There are two ways to fix it:

Option A: Set up a verified certificate (recommended)

Use this if a CA your agent machine trusts (including your own) can sign your Faddom server's certificate with a SAN covering the exact <faddom-host> you dial. Once trusted, the plain commands from Step 2 will connect directly with full verification and no extra tooling.

Generate a certificate and key with a SAN matching your <faddom-host> address:

openssl req -x509 -nodes -newkey rsa:2048 -keyout faddom.key -out faddom.pem -days 825 \   -subj "/CN=<faddom-host>" \   -addext "subjectAltName=IP:<faddom-host>"

Use DNS:<faddom-host> instead of IP:<faddom-host> in the SAN if you connect by hostname.

Install the certificate on the Faddom server. Convert it to a keystore and update the Tomcat connector following the existing steps in Changing the Faddom server SSL certificate, using the faddom.pem and faddom.key from step 1.
Trust the certificate on the agent machine, so Claude Code's and Codex's TLS checks pass:
Linux:
```
sudo cp faddom.pem /usr/local/share/ca-certificates/faddom.crt sudo update-ca-certificates
```
macOS:
```
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain faddom.pem
```
Windows: this step needs PowerShell specifically, unlike the connection commands in Step 2, because Command Prompt has no equivalent to Import-Certificate. Run the following in an elevated PowerShell window:
```
Import-Certificate -FilePath faddom.pem -CertStoreLocation Cert:\LocalMachine\Root
```
If Windows rejects the .pem file, convert it to .cer first and import that instead:
```
openssl x509 -in faddom.pem -outform der -out faddom.cer Import-Certificate -FilePath faddom.cer -CertStoreLocation Cert:\LocalMachine\Root
```
These trust steps are standard OS practice, not specific to Faddom. If your environment manages trust stores centrally (e.g. via an MDM), follow your
existing process instead.
Retry the Step 2 connect commands.

Option B: Connect with the default certificate, via a local bridge

Use this if you can't set up a verified certificate. This runs the HTTPS connection through Node instead, with certificate verification turned off for that connection only.

Requirements: Node.js 18+ installed on the agent machine, with npm/npx available on the command line (npx ships with npm 5.2+, so a standard Node.js install covers this).

mcp-remote is a third-party community npm package that bridges your agent to Faddom over HTTPS. The NODE_TLS_REJECT_UNAUTHORIZED=0 flag disables certificate verification only for that process; it does not affect your agent's own traffic or any other MCP server. Pin the version (mcp-remote@0.1.16) rather than using @latest, so a future release can't change behavior without your knowledge.

Claude Code, via bridge (replaces the Step 2 command):

claude mcp add faddom-compass --env NODE_TLS_REJECT_UNAUTHORIZED=0 -- \   npx -y mcp-remote@0.1.16 https://<faddom-host>:9443/WebServices/api/v1/mcp/compass \   --header "Authorization: Bearer <token>"

Verify with /mcp.

Codex CLI, via bridge (replaces the Step 2 command):

codex mcp add faddom-mcp --env NODE_TLS_REJECT_UNAUTHORIZED=0 -- \   npx -y mcp-remote@0.1.16 https://<faddom-host>:9443/WebServices/api/v1/mcp/compass \   --transport http-only --header "Authorization: Bearer <token>"

Verify with codex mcp list. Codex spawns stdio MCP servers with an environment table, so the bridge applies the same way: the insecure HTTPS connection happens inside Node, not inside Codex itself.

Connection refused

A firewall is blocking TCP 9443 between the agent machine and the Faddom server (the same port the Faddom web UI uses). Open that port and retry.

Faddom MCP request failed

This is a server-side error. Contact support with a copy of your Faddom-Server.log.

Need more help? Contact support@faddom.com.