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

# MCP

> Connect your own MCP server so CloudThinker agents can call its tools next to the built-in connections.

Model Context Protocol (MCP) is an open standard for exposing tools to AI agents. If you run an MCP server, for example in front of an internal metrics API, a ticketing system, or a legacy service, you can add it as a custom [connection](https://docs.cloudthinker.io/guide/connections/overview.md) and every tool it serves becomes a tool agents can call.

## Prerequisites

* An MCP server that speaks **Streamable HTTP** or **Server-Sent Events** (SSE), reachable from the internet. To limit who can reach it, allowlist CloudThinker's egress IPs. These docs don't publish CloudThinker's egress IP list: ask your CloudThinker contact, or [contact us](https://cloudthinker.io/contact).
* The server's endpoint URL, for example `https://mcp.example.com/mcp`.
* A credential for your server, if it requires one. Issue one only for CloudThinker (see [Required permissions](#required-permissions)).
* Permission to edit connections in your workspace.

> [!NOTE]
>
> CloudThinker reaches your server over the public internet and authenticates with static HTTP headers you set on the connection, usually an `Authorization` header with a token your server checks. The MCP form has no OAuth sign-in, so a server that only accepts OAuth can't be connected.

## Setup

**1. Open the MCP form**

In the sidebar, click **More → Workspace settings → Connections**, select the **MCP Connections** tab, and click **+** (**New MCP connection**). The **Create MCP Connection** dialog opens.

**2. Fill in Basic Information**

* **Connection Name**: a name your team will recognize, such as `Internal metrics`.
* **Description**: optional, up to 500 characters.
* **Prefix**: a short handle for this server, such as `metrics`. Tools appear as `metrics__tool_name`, and you'll see the prefix in approval requests and Rules.
* **Transport Type**: **Streamable HTTP** or **Server-Sent Events**, whichever your server speaks.

**3. Add headers**

Under **Headers Configuration (Optional)**, add each header your server needs as a **Key** and **Value**, for example `Authorization` and `Bearer <your-token>`. CloudThinker sends these headers on every request. Header keys must be unique.

**4. Fill in Connection Configuration**

* **URL**: the server endpoint, such as `https://mcp.example.com/mcp`. See [Server URL rules](#server-url-rules).
* **Timeout (seconds)**: how long to wait for the server to respond. Default 30, allowed 0.1 to 300. Keep 30 unless your tools run long queries, then raise it.
* **SSE Read Timeout (seconds)**: how long to wait on the event stream. Default 300, allowed 1 to 600.

**5. Create**

Click **Create**. CloudThinker contacts the server and loads its tool list.

**Success state:** the connection shows **Connected** in the **MCP Connections** list, and its detail panel shows the transport and URL under **Server config**. If it fails, a **Connection error** alert explains why. See [Troubleshooting](#troubleshooting).

> [!WARNING]
>
> Don't put credentials in the URL (`https://user:password@host/mcp`). The form rejects it. For basic auth, add a header with key `Authorization` and value `Basic <base64 of user:password>`.

## Connection details

| Field | Required | Description | Example |
| - | - | - | - |
| **Connection Name** | Yes | A name your team will recognize | `Internal metrics` |
| **Description** | No | Up to 500 characters | `Internal metrics API` |
| **Prefix** | Yes | Short handle. Tools appear as `prefix__tool_name` | `metrics` |
| **Transport Type** | Yes | **Streamable HTTP** or **Server-Sent Events** | **Streamable HTTP** |
| **URL** | Yes | The server endpoint. See [Server URL rules](#server-url-rules) | `https://mcp.example.com/mcp` |
| **Headers Configuration** | No | One **Key** and **Value** per header, sent on every request | `Authorization` / `Bearer <your-token>` |
| **Timeout (seconds)** | Yes, prefilled | Wait for a response. Default 30, allowed 0.1 to 300 | `30` |
| **SSE Read Timeout (seconds)** | Yes, prefilled | Wait on the event stream. Default 300, allowed 1 to 600 | `300` |

### Server URL rules

| URL | Result |
| - | - |
| `https://mcp.example.com/mcp` | Recommended. The certificate must come from a public certificate authority. Self-signed certificates are rejected. |
| `http://203.0.113.10:8000/mcp` | Accepted, with the warning "Not encrypted. Headers and tool results are sent as plain text." Your token travels unencrypted. |
| `http://localhost:8000/mcp`, `http://10.0.0.5/mcp`, `http://192.168.1.20/mcp` | Rejected. CloudThinker can't reach loopback, private, or cloud metadata addresses. |
| A host name that resolves to a private address | Rejected, even if it looks public. |

> [!WARNING]
>
> There's no workspace setting that blocks `http://` URLs. Use `https://` for any server that takes a token, and [add HTTPS](#add-https-with-a-reverse-proxy) if it only speaks HTTP.

### Add HTTPS with a reverse proxy

If your server only speaks HTTP, put a reverse proxy in front of it. With [Caddy](https://caddyserver.com/docs/install):

**1. Point DNS at the server**

Create a DNS `A` record, such as `mcp.example.com`, that points to the server's public IP.

**2. Configure Caddy**

Save this as your `Caddyfile`, replacing the port with the one your MCP server listens on:

```text theme={null}
mcp.example.com {
    reverse_proxy localhost:8000
}
```

**3. Start Caddy**

Open ports 80 and 443 and start Caddy. It requests a public certificate on its own.

**Success state:** `https://mcp.example.com` loads in a browser with a valid certificate. Enter `https://mcp.example.com/mcp` as the **URL**.

## Required permissions

Your server decides what the connection can do. CloudThinker only holds the header values you give it.

> [!TIP]
>
> Issue a token used only by CloudThinker, so you can revoke it without affecting anything else. Scope it to the least access the exposed tools need, start with read tools only, and have the server validate the token on every request.

## Agent capabilities

After you connect, CloudThinker loads the server's tool list. Each tool is available to agents as `prefix__tool_name`, where the prefix is the one you set on the connection. A server with prefix `weather` that exposes `get_forecast` gives agents a tool called `weather__get_forecast`.

Agents can only call tools your server serves. MCP connections have no **Allow writes** switch, so choose **Manual** and a person then approves every write tool call. Taking a tool off the server is the other control that always holds, and it is the only way to stop a read: reads always run without asking.

Once CloudThinker turns on [Rule enforcement](https://docs.cloudthinker.io/guide/approvals/rules.md#troubleshooting) for your workspace, a **Deny** [Rule](https://docs.cloudthinker.io/guide/approvals/rules.md) can refuse one write tool outright while the rest keep asking.

### How reads and writes are decided

CloudThinker sorts each tool into a read or a write when it loads the tool list:

| Check, in order | Result |
| - | - |
| The tool declares `readOnlyHint: true` | Read |
| The tool declares `destructiveHint: true` | Write |
| The tool name contains a read word: `get`, `list`, `search`, `query`, `read`, `describe`, `show`, `find`, `fetch`, `check`, `count`, `view`, `lookup`, `browse`, `inspect`, `export`, `download` | Read |
| Anything else | Write |

Name words are split on `_` and `-`, so `list_tickets` and `get-status` are reads, while `listTickets` (one word) and `close_ticket` are writes. Reads run without asking. Writes go through your [Rules](https://docs.cloudthinker.io/guide/approvals/rules.md) and [Approval mode](https://docs.cloudthinker.io/guide/approvals/approval-mode.md).

> [!WARNING]
>
> Any read word anywhere in the name makes the tool a read, unless it declares `destructiveHint: true`. `get_and_delete_user` and `check_and_fix` count as reads and run without approval. Set `destructiveHint: true` on every tool that changes data.

CloudThinker reloads the tool list, and sorts every tool again, when you click **Edit** and save a change to the URL, headers, or transport. Changing only the name or description doesn't reload it.

### Verify the connection

Start a chat and type `#` to pick the connection, then ask:

```text theme={null}
#Internal metrics List the tools this connection exposes, then call the simplest read-only one and show me the result.
```

**Success state:** CloudThinker lists the tools by their `prefix__tool_name` names and returns output from one read tool, with no approval request.

### Example prompts

Replace `#Internal metrics` with your connection's name.

```text theme={null}
#Internal metrics What is the current status of the checkout service?
#Internal metrics Compare today's error counts with the last 7 days and flag anything unusual.
#Internal metrics Which tools here can change data? Describe what each one does before calling any of them.
```

## Troubleshooting

> [accordion] This connection did not respond in time. Try connecting again.
>
> The server didn't answer within **Timeout (seconds)**. Check that the server is running and that its firewall allows CloudThinker's egress IPs, then raise the timeout and try again.

> [accordion] This server does not use HTTPS on this port.
>
> The URL starts with `https://`, but the server speaks plain HTTP on that port. Change the URL to `http://`, or [add HTTPS](#add-https-with-a-reverse-proxy).

> [accordion] This server's TLS certificate is not trusted: it is self-signed, expired, or issued for another name.
>
> Replace a self-signed certificate with one from a public certificate authority, such as Let's Encrypt. Renew an expired one. Make sure the host name in the **URL** matches the certificate.

> [accordion] This server refused the connection.
>
> Nothing is listening at that host and port. Fix the URL, or start the server.

> [accordion] URL points to a private or metadata IP address / URL resolves to a private or metadata IP address
>
> The URL contains a private address, or DNS maps the host name to one. The message "URL points to a blocked internal hostname" covers names such as `localhost`. Use a public host name or IP address.

> [accordion] Could not resolve hostname
>
> DNS has no record for the host name in your **URL**. Check the spelling. A name that only exists inside your network won't resolve.

> [accordion] The provider rejected these credentials. Update them, then connect again.
>
> Your server returned 401 or 403. Check the header key and value, confirm the token is still valid on your server, and check how the server expects it (for example `Bearer` versus a custom header).

> [accordion] The provider endpoint was not found. Check the connection settings.
>
> The host answered but the path is wrong. Many servers serve MCP at `/mcp` or `/sse`. Check your server's docs for the exact path.

> [accordion] Connected, but tools are missing
>
> Check that the server returns its tools in the tool list response and look at the server's own logs. Tools the server doesn't list can't be called.

> [accordion] SSE connection drops
>
> Raise **SSE Read Timeout (seconds)**, check that no proxy between CloudThinker and the server buffers or cuts long-lived connections, and have the server send keepalive events.

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Use HTTPS.** Over `http://`, headers, including your token, and tool results travel as plain text.
- **Mark tool hints.** Set `readOnlyHint` and `destructiveHint` so CloudThinker treats each tool the way you intend.
- **Rotate header credentials.** Replace the token on your server, then edit the connection and update the header value.

## Related

> [card] [Set approval Rules](https://docs.cloudthinker.io/guide/approvals/rules.md)
>
> Decide which of your server's write tools run, ask first, or are refused.

> [card] [Connections overview](https://docs.cloudthinker.io/guide/connections/overview.md)
>
> See every built-in connection before building your own server.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.