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

# Custom MCP

> Connect external MCP servers to extend TierZero with custom tools

## Overview

Custom MCP servers let you connect external Model Context Protocol servers to TierZero. Once connected, TierZero discovers the tools exposed by that server and can use them during investigations, support conversations, and other agent workflows.

TierZero uses the server description and your MCP-specific instructions to decide when a custom server is relevant. A strong description matters because it is part of the routing signal for when those tools should be used.

<Info>
  TierZero optimizes custom MCP connectors for production use despite claims that "MCP is dead". Simply connect the MCP servers you need for your workflows, and use MCP-specific instructions to give TierZero more context.
</Info>

## Prerequisites

* Super admin access in TierZero
* A remote MCP server reachable from TierZero over HTTPS
* One supported authentication method: Bearer Token, Custom Headers, or OAuth
* A server that successfully responds to MCP tool discovery

<Info>
  In production, custom MCP server URLs must use `https://`. `http://` URLs are only allowed in development environments.
</Info>

## Setup Instructions

### Step 1: Open Custom MCP Servers

1. Log into your TierZero dashboard
2. Go to **Settings → Integrations**
3. Open **Custom MCP Servers**
4. Click **Add Server**

### Step 2: Enter Basic Details

1. Add a **Server Name**
2. Add a **Description** that clearly explains what this server handles

Example descriptions:

* `Query and analyze PostgreSQL databases`
* `Inspect internal feature flag configuration and rollout state`
* `Search our internal observability data lake for historical incidents`

<Info>
  Server names must start with a letter and may only contain letters, numbers, and spaces. Hyphens are not allowed in the display name.
</Info>

### Step 3: Configure the Connection

1. Enter the **Server URL**
2. Choose an **Auth Type**
3. Provide the required credentials

Supported auth types:

* **Bearer Token**: Sends the token as an `Authorization: Bearer ...` header
* **Custom Headers**: Sends one or more custom header key/value pairs
* **OAuth**: Starts an OAuth authorization flow with the MCP provider

### Step 4: Test and Save

For **Bearer Token** and **Custom Headers**:

1. Click **Test Connection**
2. Confirm TierZero can connect and discover tools
3. Click **Add Server**

For **OAuth**:

1. Click **Add Server**
2. Complete the provider's OAuth flow
3. Return to TierZero after authorization completes

If setup succeeds, the server becomes active and TierZero stores the discovered tool list for that endpoint.

## How TierZero Uses Custom MCP Servers

After a server is active, TierZero can call its tools anywhere agent tool use is supported. In practice, TierZero relies on three inputs:

* The **server description** you entered in settings
* The **discovered tool list** from the MCP server
* The **MCP-specific instructions** you maintain in Knowledge & Tuning

## MCP Server Instructions

After you create a custom MCP server, TierZero adds a dedicated file for it under **Knowledge & Tuning → mcp**.

The generated file name is based on the server slug, for example:

* `pg analyze` becomes `pg-analyze.md`
* `feature flags` becomes `feature-flags.md`

Use this file to document:

* When TierZero should use this MCP server
* Which tools are most important
* Any argument conventions or required context
* Safe or unsafe usage patterns

This is the best place to tune how aggressively TierZero should reach for a given custom server.

## Limits and Behavior

* Server names must be unique within the organization
* If connection settings change, TierZero clears the active tool list and requires the connection to be tested again before the updated configuration is trusted
* A server can be saved in an inactive state if creation or update succeeds but tool discovery fails

## Security

* TierZero validates custom MCP URLs and rejects private or internal network targets
* Credentials are encrypted in transit and encrypted at rest. See [TierZero Security](https://tierzero.ai/security) for more detail
* OAuth servers can refresh tokens after setup when supported by the provider
* Access can be removed at any time by deleting the custom MCP server from TierZero

## Troubleshooting

### Test Connection Fails

* Verify the MCP server URL is correct and publicly reachable
* Confirm the auth method matches what the server expects
* For Custom Headers, make sure each header includes both a name and a value

### Server Saves But Stays Inactive

* The server record was created, but TierZero could not discover tools
* Open the server and run **Test Connection** again after fixing the endpoint or credentials

### OAuth Setup Restarts

* If TierZero does not have a valid access token for the server, testing the connection can restart the OAuth flow
* Complete the provider authorization again and return to **Settings → Integrations → Custom MCP Servers**