Connecting AI Clients

Once your gateway is running, point any MCP-compatible AI client at http://localhost:5100/mcp. This page covers Claude Desktop and the OpenAI Codex CLI.

Both clients need a valid agent JWT. See Agent Management for the full production flow (create an agent, issue a 30-day token). If you are running locally for the first time, the dev shortcut below is faster:


curl http://localhost:5100/dev/token

Copy the token value from the response. Dev tokens are valid for 8 hours and only work from localhost.

Claude Desktop

Claude Desktop currently only supports stdio-based MCP servers. Use mcp-remote as a bridge — it runs as a local stdio process and proxies traffic to the gateway over HTTP. You need Node.js (and therefore npx) installed.

Edit the config file

Open the Claude Desktop config file in a text editor:

Platform	Path
Mac	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Add the mcpServers block (create the file if it doesn’t exist):


{
  "mcpServers": {
    "ithil": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:5100/mcp",
        "--transport",
        "http-first",
        "--header",
        "Authorization: Bearer YOUR_TOKEN_HERE"
      ]
    }
  }
}

Replace YOUR_TOKEN_HERE with the token from above.

The --transport http-first flag is required. Without it, mcp-remote tries an OAuth discovery flow that the gateway does not implement, and the connection fails.

Restart Claude Desktop

Quit and reopen Claude Desktop. A tools icon will appear in the message bar when the connection is live.

Try it

Ask Claude to use your tools naturally:

“Fetch post number 5 for me.”

“What’s the title of post 12?”

“Get me the details for user ID 3.”

Claude will call the appropriate tool through the gateway and return the result. If you have user endpoints, notice that email addresses come back as [EMAIL REDACTED] — the PII filter applied automatically, with no changes to your API.

In production, use a 30-day token issued via the management API — see Agent Management. The dev token is a local shortcut only.

OpenAI Codex CLI

Codex Desktop requires bearer auth to be declared via an environment variable — inline headers in config.toml are parsed but not used for authentication. Use the codex mcp add command to register the server correctly.

Register the MCP server


codex mcp add ithil --url http://localhost:5100/mcp --bearer-token-env-var ITHIL_BEARER_TOKEN

This writes the following to ~/.codex/config.toml:


[mcp_servers.ithil]
url = "http://localhost:5100/mcp"
bearer_token_env_var = "ITHIL_BEARER_TOKEN"

Set the token environment variable

Get a dev token:


curl http://localhost:5100/dev/token

Then export the token value before starting Codex:


export ITHIL_BEARER_TOKEN="YOUR_TOKEN_HERE"
codex

For convenience, add the export to your shell profile (~/.zshrc or ~/.bashrc) and refresh it when the token expires.

Do not use the headers = { Authorization = "Bearer ..." } TOML format. Codex parses it without error but does not use it for authentication, so the connection will be rejected by the gateway.

Try it


codex "Fetch post number 5"


codex "What are the details for user ID 3?"

Codex will discover the available tools from the gateway and call the right one.

In production, use a 30-day token issued via the management API — see Agent Management. The dev token is a local shortcut only.

Example prompts

These prompts work against the SampleApi’s JSONPlaceholder endpoints. Use them to demo the full flow:

Prompt	Tool called	What it shows
”Fetch post number 5”	`GetPost`	Basic read-only tool call
”Get me the comments on post 2”	`GetComments`	Tool with a query parameter
”What’s the email address for user 1?”	`GetUser`	PII filter — email returns as `[EMAIL REDACTED]`
”Create a post titled ‘Hello’ by user 1 with body ‘Test post‘“	`CreatePost`	Write tool (`AllowWrite = true`)