Connect & Use

Connect an MCP client

MCP Gateway Pro serves every tool on the appliance (the built-in RAG, media and web search tools and the MCP servers you add) at one endpoint, authenticated with an API key.

Endpoints

Authenticate every request with the header Authorization: Bearer <your API key>. There is no OAuth sign-in: a client that offers one is missing this header.

The console's API Keys page shows these settings for your appliance under "Connect an MCP client", and the create-key dialog shows them with the new key already filled in. The server name used below is appxen.

claude mcp add --transport http appxen "https://<your appliance address>/mcp" --header "Authorization: Bearer <your API key>"

{
  "mcpServers": {
    "appxen": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your appliance address>/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer <your API key>" }
    }
  }
}

API keys

Create and manage keys in the console, under API Keys in the sidebar. The page shows the connection settings for your appliance under "Connect an MCP client", and the create-key dialog shows them with the new key already filled in. A key starts with axgw_live_k1_ followed by 32 random characters, and it is shown once, when you create it.

Limits

• You can hold at most 10 keys. A request to create more is refused (HTTP 400).
• Each key has a per-minute limit, set when you create it. The default is 1000.

What the limit counts

Only requests authenticated with an API key on the MCP routes count, one per HTTP request (a JSON-RPC batch counts as one):

• POST /mcp and POST /mcp/<alias>
• DELETE /mcp and DELETE /mcp/<alias>
• GET /mcp/sse and POST /mcp/sse/message

These do not count: /api/rag/*, /api/extensions/*, /api/builtins/*, a request that fails authentication, and a cookie session.

When a key reaches its limit

The limit is counted over a 60-second sliding window. Below the limit, a request is recorded and the response carries X-RateLimit-Limit, X-RateLimit-Remaining (the limit minus the requests now in the window) and X-RateLimit-Reset (when the oldest request in the window leaves it).

At the limit the gateway answers 429 with {"detail":"Rate limit exceeded"} and a Retry-After header (an integer from 1 to 60, counting to that reset). A request refused this way is not recorded, so a client that keeps retrying is released when its oldest accepted request ages out, not 60 seconds after its last retry.

If Redis is unreachable, the request is let through, with no X-RateLimit-* headers.

Register MCP servers

Add the MCP servers and REST APIs your team uses in the console, on the MCP Gateway page, with Add Server. A registered server may be at a public address or at a private address in your VPC. For examples of what to register, see the MCP Gateway Pro quickstart.

Addresses that are never reachable

A link-local address (169.254.0.0/16 or fe80::/10, which include the instance metadata service) and the metadata service's IPv6 range (fd00:ec2::/32) are never reachable, whatever you allow. A wider range that contains them is accepted, and they stay unreachable inside it.

Servers that need an allow-upstream entry

Two kinds of server are refused until you allow them on the instance with sudo appxenctl allow-upstream <name>, where the name is a host name, an address or a CIDR range:

• A server on the appliance itself. That means a container on one of the appliance's Docker networks, or a process on the instance that the gateway reaches at a Docker network address; a loopback address (127.0.0.1, ::1) counts as well. A process that listens on the instance's own VPC address is reached like any other private address in your VPC and needs no entry.
• A server behind a single-label host name (one without a dot), such as a container name.

# Allow an entry (restarts the gateway and prints the list)
sudo appxenctl allow-upstream <name>

# Show the list
sudo appxenctl allow-upstream --list

# Take an entry off the list
sudo appxenctl allow-upstream --remove <name>

The command restarts the gateway and prints the list. A host name is not looked up when you add it: it is trusted for whatever address it resolves to when a server connects, except the never-reachable ranges above. An IPv4-mapped IPv6 address or range is stored as its IPv4 form, which is the one the gateway matches.

A range wide enough to cover the appliance's own loopback or its internal Docker networks (0.0.0.0/0, 127.0.0.0/8, 172.16.0.0/12) is accepted as well, and the command warns you when you add one. Such an entry also allows the appliance's own loopback and internal Docker networks, so every signed-in user can then reach the appliance's internal services through the gateway.

Web search

Web search is optional. The gateway's web search tools, web_search and web_extract, need a Brave Search API key of your own. Without a key they are not listed, and a workflow step that asks for web search fails with a message naming the command below, instead of running without search. With a key set, web_search calls the Brave Search API and web_extract fetches the pages it is asked for directly.

To add the key, run this on the instance and paste the key at its prompt (the key is not shown as you paste it, and nothing is left behind):

sudo appxenctl set-brave-key

If you must use a file instead, create it readable only by you, run the command below, and delete the file afterwards:

sudo appxenctl set-brave-key < brave-key.txt

The command saves the key, restarts the gateway and reports whether the web search tools are now listed. The key is never passed on the command line.

sudo appxenctl set-brave-key --clear removes the key again.

Command-line client

The appxen command-line client works against your appliance, from your own machine or from the instance itself. It checks the appliance's status, ingests documents into the RAG Engine, searches them and runs Agent Orchestrator workflows. It needs Python 3.10 or newer.

Install

pip install appxen

# or
curl -fsSL https://appxen.ai/install.sh | sh

Sign in

The endpoint is the stack's ConsoleUrl output, or https://<your domain> once you have run sudo appxenctl set-domain <name>. With a domain set, always pass the domain as the endpoint, on the instance too.

appxen login --endpoint <ConsoleUrl>

The API key is one you create in the console, under API Keys (see "Create an API key" above). Type it at the hidden prompt, or pipe it on stdin in a script. The CLI has no option for the key, so it is never on the command line:

printf '%s\n' "$APPXEN_KEY" | appxen login --endpoint <ConsoleUrl>

Use it

appxen status
appxen ingest ./docs/
appxen search "how does authentication work"
appxen workflow run <id>

appxen status checks the connection and the key, appxen ingest uploads a file or a directory into the RAG Engine, appxen search searches it and appxen workflow run runs a workflow.

The profile (the endpoint and the key) is stored in ~/.config/appxen/config.toml, mode 0600, in a directory of mode 0700. The CLI guide has every command and option.