# Connecting an MCP Client

An [MCP Endpoint](/products/ai-studio/agent-channels/mcp-endpoints) turns one shared work folder into a remote MCP server. A client connected to it gets six tools: two to find out what the folder offers, three to start or continue work, and one to collect a result. The work runs in Treasure AI Studio, not in the client. The client calls a tool, Studio starts a chat in the folder with the executor's permissions and connections, and the tool returns the agent's answer.

This page covers configuring a client, what each tool does, and how to read what comes back. It is for whoever sets up the client and for anyone writing an agent against the endpoint directly. To create the endpoint and get its URL and token, see [Creating and Managing an MCP Endpoint](/products/ai-studio/agent-channels/mcp-endpoints).

## How a Tool Call Becomes Work in Studio

```mermaid
flowchart LR
    A["MCP client<br/>holds the token"] -->|"POST to the endpoint URL<br/>Authorization: Bearer"| B["Agent Gateway"]
    B -->|"Check the token<br/>on every request"| C["Treasure AI Studio"]
    C -->|"Start or continue a chat<br/>in the shared work folder"| D["Agent<br/>runs as the executor"]
    D -->|"Answer"| B
    B -->|"Tool result"| A
```

1. **The client sends a tool call** to the endpoint's URL with the token in the `Authorization` header.
2. **Treasure AI Studio checks the token on every request** — that it belongs to this endpoint and has not expired or been revoked, that the endpoint is enabled and has an executor, and that the executor still has access to the folder.
3. **Tools that start work open a chat** in the endpoint's folder. The chat runs as the executor, reads the folder read-only, and writes only to a temporary work area that is discarded with the chat.
4. **The gateway waits for the answer** and returns it as the tool result. If the agent is still working when the wait runs out, the result says so and gives the chat ID to come back with. The chat keeps running.


There is one credential. The endpoint's Gateway Token goes in the header of every request, and no per-chat token is issued or exchanged. [Gateway Tokens and Chat Access Tokens](/products/ai-studio/agent-channels/tokens) covers issuing, rotating, and revoking it.

## Configure the Client

The endpoint speaks MCP over **Streamable HTTP** and needs a client that can send a fixed header with every request. Give the client the values from the endpoint's completion screen:

| Setting  | Value  |
|  --- | --- |
| **Server URL** | The endpoint's **Connection URL**, `https://<your account's Agent Gateway>/v1/mcp/<endpoint ID>` |
| **Transport** | Streamable HTTP |
| **Header** | `Authorization: Bearer tasgwt_<the secret>` |


The endpoint authenticates with this static header only. It does not offer OAuth, so a client that expects to sign in through a browser has nothing to sign in to. Enter the header as a fixed value in the client's configuration, or keep the token in a secret manager. Do not put it in a web page's code.

To check the values before configuring a client, list the tools with the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) from a shell:

```bash
npx @modelcontextprotocol/inspector --cli "$MCP_SERVER_URL" \
  --transport http \
  --header "Authorization: Bearer $MCP_TOKEN" \
  --method tools/list
```

Set `MCP_SERVER_URL` to the endpoint's **Connection URL** and `MCP_TOKEN` to its `tasgwt_` token first. A working endpoint answers with the six tools below. A `401` means the token was refused; a `403` means the endpoint is disabled or cannot run, or the request carried an `Origin` header. See [Troubleshooting](#troubleshooting).

## The Tools

| Tool  | What It Does  | Arguments  |
|  --- | --- | --- |
| `list_work_folders` | Lists the work folders available through the connection. An endpoint publishes exactly one, so the list always has one entry with its `id` and `name` | None |
| `list_actions` | Lists the folder's Actions, each with its `name` and `description`, sorted by name | `work_folder_id` |
| `run_action` | Starts a new chat that runs an Action with its saved instructions, then waits for the result. Each call is a separate run | `work_folder_id`, `action_name` |
| `start_chat` | Starts a new chat with the task in `message`, then waits for the result. Use it when no Action fits | `work_folder_id`, `message` |
| `continue_chat` | Sends a new instruction to an existing chat, to ask for more work or a revision, then waits for the reply | `chat_id`, `message` |
| `get_chat_result` | Reads the result of the chat's latest instruction, including one sent with `continue_chat`, without sending anything. Waits if the chat is still running | `chat_id` |


Every endpoint offers all six, and an endpoint cannot hide any of them. Arguments are checked against each tool's published schema before anything runs. Unknown arguments are refused rather than ignored, and every problem with a call is reported together in one error.

### Which Actions Are Listed

`list_actions` returns the [Actions](/products/ai-studio/skills/actions) defined in the endpoint's shared work folder. Pass the `name` it returns to `run_action`. The list is read when the tool is called, so an Action added to the folder is available to the client right away.

### Run an Action or Start a Chat

`run_action` takes no input beyond the Action's name: no arguments and no extra instructions. It runs the Action exactly as it is saved, which makes it the predictable choice and the one the tool descriptions steer a client toward first.

`start_chat` takes a task in plain language instead. The agent in Studio does not see the client's conversation, so `message` has to carry everything the task needs: the context, the data to use, and what the result should look like.

Use `continue_chat` to send an instruction on an existing chat. Use `get_chat_result` to wait for an answer that is still being produced. Calling a starting tool again for the same task starts a second, separate run.

## Read a Result

Every tool answers with one JSON object in a text block. `list_work_folders` and `list_actions` return their data directly. The four tools that work with a chat return an object whose `status` says what happened:

| `status`  | Meaning  | What to Do Next  |
|  --- | --- | --- |
| `completed` | The turn finished. `result` holds the agent's answer as text | Read `result` |
| `running` | The agent was still working when the gateway's wait ran out. The chat has not stopped | Call `get_chat_result` with the `chat_id`. Do not start another run or resend the instruction |
| `question` | The agent asked a question instead of answering. `question` holds it. The gateway declines it on your behalf, and `declined` says whether that was confirmed; when it is `true`, the agent carries on without an answer | Call `get_chat_result` to read the outcome. To change the direction of the work, send a `continue_chat` |
| `failed` | The turn ended in failure. `error` is one of a fixed set of messages, and the underlying reason stays inside the platform | Decide whether to retry; there is nothing more to read from this result |
| `unknown` | The result could not be read. The chat may still be running | Call `get_chat_result` with the `chat_id`. Do not repeat the original instruction |


The wait exists because MCP clients put a time limit on a tool call, and an Action can take longer than that. The gateway waits up to 200 seconds, then answers `running` with the chat ID rather than letting the client time out. A client that calls `get_chat_result` in a loop until the status changes will reach the final status.

Only the agent's text comes back. The agent's reasoning, the tools it called, and their output are not included, and neither are any files it wrote, because the work area is discarded with the chat. Anything the client needs has to be in the answer, so for an Action that produces a file, have the Action say what it produced.

### Follow-Ups Stay on the Same Endpoint

`continue_chat` and `get_chat_result` reach only chats that were started through the same endpoint. A chat started with one token can be continued with another token of the same endpoint, so rotating a token does not cut off a conversation. A chat ID from a different endpoint, or from a chat started in Studio, is answered with `not_found`, even when the folder is the same.

The chats themselves belong to the executor and appear in their Studio chat list, labelled **MCP** and shown with a conversation icon of two speech bubbles.

Recent Chats in the sidebar showing a chat labelled MCP above its title, with a conversation icon of two speech bubbles
## Limits

| Limit  | Value  |
|  --- | --- |
| **New chats** | 30 per minute per endpoint, counted across `run_action` and `start_chat` and across all of the endpoint's tokens. Over the limit, the tool answers `rate_limited` |
| **Message length** | 1 to 32,768 characters for `start_chat` and `continue_chat` |
| **Wait per tool call** | Up to 200 seconds, then `running` |
| **Folders per endpoint** | One |
| **Requests per call** | One JSON-RPC message per HTTP request. Batches are refused |


The connection is stateless. There is no MCP session to open or close, so `POST` is the only HTTP method the endpoint accepts, and a client that drops its connection mid-call does not stop the chat it started.

## What Is Not Supported

- **Answering the agent's questions.** A question is always declined automatically, and the result reports it as `status: "question"`.
- **Arguments for an Action.** `run_action` runs the Action as saved. To pass input, use `start_chat` and describe the task.
- **Choosing a different folder or executor per call.** Both are fixed on the endpoint.
- **Resources, prompts, and other MCP capabilities.** The endpoint offers tools only.
- **OAuth sign-in.** The endpoint authenticates with its static header only.
- **Browsers.** Requests with an `Origin` header are refused.


## Errors

A call can fail at two levels. A refused credential fails the whole HTTP request; a problem with one tool call comes back as a tool result with `isError` set.

| Response  | Meaning  |
|  --- | --- |
| HTTP `401` with `invalid_token` | The token is unknown, revoked, or expired, or it belongs to a different endpoint, or the endpoint has been deleted. All of these look the same from outside |
| HTTP `403` with `mcp_disabled` | The endpoint is disabled or has no executor, or the executor has lost access to the folder |
| HTTP `403` with `browser_refused` | The request carried an `Origin` header |
| HTTP `405` | The client used `GET` or `DELETE`. Only `POST` is accepted |
| HTTP `406` | The request's `Accept` header did not include both `application/json` and `text/event-stream` |
| JSON-RPC error *"The service is temporarily unavailable."* | Treasure AI Studio could not be reached for this call. Nothing was started; try again |
| Tool error `invalid_request` | The arguments did not match the tool's schema. The message lists every problem |
| Tool error `not_found` | The folder ID, Action name, or chat ID does not exist or is not reachable through this endpoint |
| Tool error `rate_limited` | Too many chats were started on this endpoint in the last minute. Try again later |
| Tool error `dispatch_failed` | The Action, chat, or follow-up could not be started. Try again |
| Tool error `folder_unavailable` | The folder's contents could not be read at that moment. Try again |


## Troubleshooting

| Symptom  | Cause and Fix  |
|  --- | --- |
| Every request is refused with `401` | Check that the header is `Authorization: Bearer <token>` with the full token, and that the URL and token come from the same endpoint. If they do, the token has expired or been revoked — issue a new one on the endpoint's detail page |
| Every request is refused with `403` | Open the endpoint in **Settings → Agent Channels** and check its status. If it is **Disabled** or **Stopped — needs an executor**, it has to be enabled again; if it is **Active**, the executor may have lost access to the folder |
| `list_actions` returns nothing, or not the Action you expected | The Action is not defined in the endpoint's shared work folder. Open the folder in Studio and check that it appears as an Action in the **Actions and Skills** section — see [Actions](/products/ai-studio/skills/actions) |
| A tool keeps returning `running` | The chat is still working. Keep calling `get_chat_result` with the same `chat_id`; to see progress, the executor can open the chat in Studio |
| `continue_chat` answers `not_found` for a chat you started | The chat was started through a different endpoint, or it has been deleted. Follow-ups work only on the endpoint that started the chat |


## Next Steps

- [Creating and Managing an MCP Endpoint](/products/ai-studio/agent-channels/mcp-endpoints) — the endpoint, its executor, and its tokens.
- [Actions](/products/ai-studio/skills/actions) — write the Actions the client runs.
- [What an Agent Channel Chat Can Reach](/products/ai-studio/agent-channels/channel-chats) — the workspace, credentials, and limits behind each chat.
- [Gateway Tokens and Chat Access Tokens](/products/ai-studio/agent-channels/tokens) — rotate and revoke the endpoint's token.