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

# MCP Server

> Connect Tess AI to Claude, Cursor, Codex, and any MCP-compatible platform — securely, with your own API token.

The **Tess AI MCP Server** turns your Tess agents, executions, and memories into tools that any **Model Context Protocol (MCP)** client can call. It is a **hosted, managed endpoint**: there is nothing to install, package, or run.

Point your AI platform at a single URL, authenticate with your **Tess API token**, and your team can list, run, and orchestrate Tess agents directly from the tools they already use.

<Note>
  **Endpoint:** `https://mcp.tess.im` — a remote MCP server using the **Streamable HTTP** transport. No `npx`, no local process, no Node.js required.
</Note>

## Why connect through MCP

<CardGroup cols={2}>
  <Card title="Use Tess where your team already works" icon="plug">
    Run Tess agents from inside Claude, Cursor, Codex, or your own internal tools — no context switching, no copy-paste.
  </Card>

  <Card title="Zero install, always up to date" icon="cloud">
    A managed endpoint maintained by Tess. New capabilities appear automatically; there is no client to upgrade.
  </Card>

  <Card title="Governed by your workspace" icon="shield-check">
    Every call runs with the caller's own API token and workspace, inheriting your existing roles, permissions, and credit limits.
  </Card>

  <Card title="Standard & portable" icon="arrows-rotate">
    Built on the open Model Context Protocol. The same endpoint works across every MCP-compatible platform — no per-vendor integration.
  </Card>
</CardGroup>

## What the server exposes

The tool surface is **generated automatically from the Tess API** — every endpoint becomes an MCP tool, so new API capabilities show up without any change to the server. Every tool is listed below, grouped by domain, each with its own linkable entry in [Tools reference](#tools-reference).

| Domain                  | Tools                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agents**              | [`list_agents`](#list-agents) · [`get_agent`](#get-agent) · [`execute_agent`](#execute-agent) · [`list_files_agent`](#list-files-agent) · [`link_files_agent`](#link-files-agent) · [`delete_file_link_agent`](#delete-file-link-agent) · [`list_agent_responses`](#list-agent-responses) · [`get_agent_response`](#get-agent-response) · [`list_agent_webhooks`](#list-agent-webhooks) · [`create_agent_webhook`](#create-agent-webhook) · [`agent_chat_completions`](#agent-chat-completions) |
| **Files**               | [`list_files`](#list-files) · [`upload_file`](#upload-file) · [`get_file`](#get-file) · [`delete_file`](#delete-file) · [`process_file`](#process-file) · [`resolve_durable_file_reference`](#resolve-durable-file-reference)                                                                                                                                                                                                                                                                   |
| **Memories**            | [`list_memories`](#list-memories) · [`create_memory`](#create-memory) · [`update_memory`](#update-memory) · [`delete_memory`](#delete-memory) · [`import_memories_text`](#import-memories-text) · [`get_memory_import_status_result`](#get-memory-import-status-result)                                                                                                                                                                                                                         |
| **Webhooks**            | [`list_webhooks`](#list-webhooks) · [`delete_webhook`](#delete-webhook)                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **Credits & workspace** | [`deduct_credits_user`](#deduct-credits-user) · [`get_workspace_usage`](#get-workspace-usage)                                                                                                                                                                                                                                                                                                                                                                                                   |

<Info>
  This list covers every tool relevant to a third-party integration. Folder/chat-organization tools (used internally by the Tess web UI) exist too but aren't documented here — ask your assistant to "list available tools" to see the full, current set from your MCP client directly.
</Info>

## Before you start

You need two things from the Tess platform:

<Steps>
  <Step title="Your API token">
    Generate a personal access token in **[Tess AI → API Tokens](https://tess.im/dashboard/user/tokens)**. This is the same token used across the Tess API — see [Quickstart](https://docs.tess.im/api/get-started/quickstart) for details.
  </Step>

  <Step title="Your workspace ID">
    The MCP server is **workspace-scoped**. Find your workspace ID in the Tess dashboard URL or workspace settings, and use the one whose agents you want to reach. Every call is isolated to that workspace.
  </Step>
</Steps>

<Warning>
  Treat your API token like a password. It grants access to your workspace's agents and executions, which may consume credits. Prefer a dedicated token per integration so you can revoke it independently.
</Warning>

## Authenticating

Credentials are sent as **HTTP headers only** — never as URL query parameters, so tokens don't end up in logs or browser history:

```
Authorization: Bearer YOUR_API_TOKEN
x-workspace-id: YOUR_WORKSPACE_ID
```

Both headers are required on every request. **Required as of 2026-09-01** for Tess API workspace scoping (same header policy as the REST API). There is no query-parameter fallback — your MCP client must support setting custom headers on the connection.

## Connect your platform

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add tess --transport http https://mcp.tess.im \
      --header "Authorization: Bearer YOUR_API_TOKEN" \
      --header "x-workspace-id: YOUR_WORKSPACE_ID"
    ```

    Then, in a session: *"Use Tess to run the Code Review agent on this diff."*
  </Tab>

  <Tab title="Cursor / VS Code">
    Add Tess to your MCP configuration (in Cursor: **Tools & Integrations → MCP Tools**, or `~/.cursor/mcp.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "tess": {
          "url": "https://mcp.tess.im",
          "headers": {
            "Authorization": "Bearer YOUR_API_TOKEN",
            "x-workspace-id": "YOUR_WORKSPACE_ID"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex CLI">
    Add a remote MCP server with headers in `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.tess]
    url = "https://mcp.tess.im"
    headers = { Authorization = "Bearer YOUR_API_TOKEN", "x-workspace-id" = "YOUR_WORKSPACE_ID" }
    ```

    <Note>Config syntax can change between Codex CLI versions — check `codex mcp --help` or the current Codex docs if this doesn't match what you see.</Note>
  </Tab>

  <Tab title="Claude Desktop / ChatGPT / other">
    These platforms connect to remote MCP servers through a "custom connector" UI. To work with Tess, the platform's connector configuration must let you set **two** things:

    * The endpoint URL: `https://mcp.tess.im`
    * **Two** custom headers: `Authorization: Bearer YOUR_API_TOKEN` and `x-workspace-id: YOUR_WORKSPACE_ID`

    Some connector UIs only expose a single bearer-token field and don't support adding a second custom header — check your platform's current documentation for whether custom headers (beyond a bearer token) are supported for remote MCP connectors. If your platform only supports a single auth header, use one of the header-capable clients above (Claude Code, Cursor, Codex CLI) or a custom integration instead.
  </Tab>
</Tabs>

## How authentication works

The MCP server is a **stateless gateway**. It does not store your credentials. On every request it:

1. Reads your API token and workspace ID from the request headers.
2. Forwards the call to the Tess API **as you**, exactly as a direct API call would.
3. Returns the result to your MCP client.

This means the server inherits **all** of your platform's existing controls:

<CardGroup cols={2}>
  <Card title="Identity & permissions" icon="user-shield">
    Calls run with the token owner's identity. Agent visibility, roles, and feature permissions are enforced by Tess, not bypassed.
  </Card>

  <Card title="Workspace isolation" icon="building-lock">
    Every request is bound to the `x-workspace-id` you send. One token cannot reach another workspace's data.
  </Card>

  <Card title="Credit governance" icon="coins">
    Executions consume credits under your existing workspace limits and billing — the same as the Tess API.
  </Card>

  <Card title="Revocable access" icon="key">
    Revoke a token in the dashboard to instantly cut off any connected platform using it. No redeploy needed.
  </Card>
</CardGroup>

## Tools reference

<h3 id="list-agents">
  list\_agents
</h3>

Lists agents available in the workspace, with search and pagination.

<ParamField path="q" type="string">Search agents by title, description, and long description.</ParamField>
<ParamField path="type" type="string">Filter by agent type.</ParamField>
<ParamField path="page" type="integer" default="1">Page number for pagination.</ParamField>
<ParamField path="per_page" type="integer" default="15">Number of agents per page.</ParamField>

<h3 id="get-agent">
  get\_agent
</h3>

Returns the full details of a single agent (inputs, type, description).

<ParamField path="id" type="string | integer" required>The agent ID.</ParamField>

<h3 id="execute-agent">
  execute\_agent
</h3>

Runs an agent with the given inputs and, optionally, waits for the result.

<ParamField path="id" type="string | integer" required>The agent ID.</ParamField>
<ParamField path="body" type="object" required>The agent's answers. For chat-type agents, include a `messages` array (`role`/`content` pairs, same shape as the OpenAI Chat Completions format).</ParamField>
<ParamField path="wait_execution" type="boolean" default="false">When `true`, waits for the execution to finish and returns the final output. When `false`, returns immediately so you can poll the execution later.</ParamField>

<h3 id="list-files-agent">
  list\_files\_agent
</h3>

Gets a list of files associated with a specific agent.

<ParamField path="agentId" type="integer" required>ID of the agent to retrieve files for.</ParamField>

<h3 id="link-files-agent">
  link\_files\_agent
</h3>

Associates one or more files with a specific agent.

<ParamField path="agentId" type="integer" required>ID of the agent to link files to.</ParamField>
<ParamField path="file_ids" type="integer[]" required>Array of file IDs to link to the agent.</ParamField>

<h3 id="delete-file-link-agent">
  delete\_file\_link\_agent
</h3>

Removes the association between a specific file and an agent.

<ParamField path="agentId" type="integer" required>ID of the agent to remove the file link from.</ParamField>
<ParamField path="fileId" type="integer" required>ID of the file to unlink from the agent.</ParamField>

<h3 id="list-agent-responses">
  list\_agent\_responses
</h3>

Lists agent execution responses, with filtering and pagination.

<ParamField path="q" type="string">Search agents by title.</ParamField>
<ParamField path="root_id" type="integer">Filter by root execution ID.</ParamField>
<ParamField path="agent_id" type="integer">Filter by agent ID.</ParamField>
<ParamField path="type" type="string">Filter by agent type.</ParamField>
<ParamField path="sort" type="string" default="asc">Sort by ascending or descending (`asc`/`desc`).</ParamField>
<ParamField path="page" type="integer" default="1">Current page.</ParamField>
<ParamField path="per_page" type="integer" default="15">Number of items per page.</ParamField>

<h3 id="get-agent-response">
  get\_agent\_response
</h3>

Fetches a single agent execution response by ID.

<ParamField path="id" type="string | integer" required>The agent execution ID.</ParamField>

<h3 id="list-agent-webhooks">
  list\_agent\_webhooks
</h3>

Lists webhooks registered for a specific agent.

<ParamField path="id" type="integer" required>Agent ID.</ParamField>
<ParamField path="page" type="integer" default="1">Current page.</ParamField>
<ParamField path="per_page" type="integer" default="15">Number of items per page.</ParamField>

<h3 id="create-agent-webhook">
  create\_agent\_webhook
</h3>

Registers a new webhook on a specific agent.

<ParamField path="id" type="string | integer" required>The agent ID.</ParamField>
<ParamField path="url" type="string">The webhook target URL.</ParamField>
<ParamField path="method" type="string" default="POST">HTTP method used for the webhook call.</ParamField>
<ParamField path="status" type="string" default="active">Webhook status (`active`/inactive).</ParamField>

<h3 id="agent-chat-completions">
  agent\_chat\_completions
</h3>

Runs an agent through an OpenAI-compatible Chat Completions interface — useful for clients already integrated against the OpenAI API shape.

<ParamField path="id" type="string | integer" required>The agent ID.</ParamField>
<ParamField path="body" type="object" required>An OpenAI Chat Completions-shaped request body.</ParamField>

<h3 id="list-files">
  list\_files
</h3>

Gets a paginated list of files in the workspace, with sorting options.

<ParamField path="page" type="integer" default="1">Page number for pagination.</ParamField>
<ParamField path="per_page" type="integer" default="15">Number of items per page (max 100).</ParamField>
<ParamField path="order" type="string" default="desc">Sort order for the `created_at` field (`asc`/`desc`).</ParamField>

<h3 id="upload-file">
  upload\_file
</h3>

Uploads a new file to the workspace and optionally processes it.

<ParamField path="file" type="binary" required>The file to upload.</ParamField>
<ParamField path="process" type="boolean" default="false">Whether to process the file immediately after upload.</ParamField>

<h3 id="get-file">
  get\_file
</h3>

Returns the details of a single file.

<ParamField path="fileId" type="integer" required>The file ID.</ParamField>

<h3 id="delete-file">
  delete\_file
</h3>

Deletes a file from the workspace.

<ParamField path="fileId" type="integer" required>The file ID.</ParamField>

<h3 id="process-file">
  process\_file
</h3>

Triggers (or re-triggers) processing for an already-uploaded file.

<ParamField path="fileId" type="integer" required>The file ID.</ParamField>

<h3 id="resolve-durable-file-reference">
  resolve\_durable\_file\_reference
</h3>

Resolves a durable `doc://<universal_id>` artifact reference (as returned in a `ref_url`) into a freshly minted, short-lived signed download URL. Identity and workspace scope come from your API token.

<ParamField path="ref" type="string" required>The durable artifact reference to resolve.</ParamField>

<h3 id="list-memories">
  list\_memories
</h3>

Lists memories stored in the workspace.

<ParamField path="collection_id" type="integer">Filter by memory collection.</ParamField>
<ParamField path="page" type="integer" default="1">Page number for pagination.</ParamField>
<ParamField path="per_page" type="integer" default="10">Items per page (max 50).</ParamField>

<h3 id="create-memory">
  create\_memory
</h3>

Saves a new memory to a collection.

<ParamField path="collection_id" type="integer">The memory collection to store the memory in.</ParamField>
<ParamField path="memory" type="string">The memory text to store (max 32,000 characters).</ParamField>

<h3 id="update-memory">
  update\_memory
</h3>

Edits an existing memory.

<ParamField path="memory_id" type="integer" required>The memory to update.</ParamField>
<ParamField path="memory" type="string">New memory text.</ParamField>
<ParamField path="collection_id" type="integer">Move the memory to a different collection.</ParamField>

<h3 id="delete-memory">
  delete\_memory
</h3>

Removes an existing memory.

<ParamField path="memory_id" type="integer" required>The memory to delete.</ParamField>

<h3 id="import-memories-text">
  import\_memories\_text
</h3>

Triggers a bulk memory import from free text. Async by default.

<ParamField path="wait" type="boolean" default="false">Whether to block until the import completes (bounded timeout) instead of returning immediately.</ParamField>

<h3 id="get-memory-import-status-result">
  get\_memory\_import\_status\_result
</h3>

Returns the status and summary for a memory-import execution.

<ParamField path="id" type="string | integer" required>The import execution ID.</ParamField>

<h3 id="list-webhooks">
  list\_webhooks
</h3>

Lists all webhooks in the workspace.

<ParamField path="page" type="integer" default="1">Current page.</ParamField>
<ParamField path="per_page" type="integer" default="15">Number of items per page.</ParamField>

<h3 id="delete-webhook">
  delete\_webhook
</h3>

Deletes a webhook by ID.

<ParamField path="id" type="integer" required>The webhook ID.</ParamField>

<h3 id="deduct-credits-user">
  deduct\_credits\_user
</h3>

Deducts credits from a specific user based on the credit-system base factor and calculation parameters. Intended for platform-level integrations metering usage of a custom resource.

<ParamField path="tess_external_identifier" type="integer" required>Identifier for the user/workspace whose credits will be deducted.</ParamField>
<ParamField path="resource_type" type="string" required>Type of resource being metered (e.g. `image`).</ParamField>
<ParamField path="resource_amount" type="number" required>Positive numeric value used for the credit calculation.</ParamField>
<ParamField path="workspace_id" type="integer">The workspace ID.</ParamField>
<ParamField path="resource_id" type="string">ID of the resource being metered.</ParamField>
<ParamField path="inputs" type="object">Additional inputs for the credit calculation.</ParamField>

<h3 id="get-workspace-usage">
  get\_workspace\_usage
</h3>

Returns workspace usage broken down by type and date range.

<ParamField path="range" type="string">Preset date range filter (`1d`/`7d`/`30d`).</ParamField>
<ParamField path="start_date" type="string">Custom start date (`YYYY-MM-DD`). Use with `end_date`; overrides `range`.</ParamField>
<ParamField path="end_date" type="string">Custom end date (`YYYY-MM-DD`). Use with `start_date`; overrides `range`.</ParamField>
<ParamField path="user_id" type="integer">Filter by user ID (requires the `WORKSPACE_DOCUMENTS_READ` permission).</ParamField>
<ParamField path="type" type="string">Filter by usage type (`chat`, `image`, `text`, `tool_execution`, `connector_calls`, and more).</ParamField>
<ParamField path="page" type="integer" default="1">Page number for pagination.</ParamField>

## Example: run an agent end to end

Once connected, you can drive a full workflow in natural language:

<Steps>
  <Step title="Discover agents">
    *"List my Tess agents"* → the assistant calls [`list_agents`](#list-agents) and shows what's available.
  </Step>

  <Step title="Capture context as memory">
    *"Save to my 'Engineering Standards' collection: always write unit tests with BDD"* → [`create_memory`](#create-memory).
  </Step>

  <Step title="Run an agent">
    *"Use the Code Review agent to review this function, and wait for the result"* → [`execute_agent`](#execute-agent) returns the output inline.
  </Step>

  <Step title="Reuse later">
    *"List my memories"* → [`list_memories`](#list-memories) confirms what's stored for future runs.
  </Step>
</Steps>

## Governance & compliance

* **Least privilege** — connect with a token scoped to a single workspace and only the permissions that integration needs.
* **Auditability** — executions triggered through MCP appear in your Tess workspace history and usage, just like any API call.
* **No credential storage** — the gateway is stateless; tokens live only in your MCP client's configuration.
* **Centralized revocation** — disabling a token in the dashboard immediately blocks every platform using it.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The client connects but no tools appear">
    Confirm your client uses the **Streamable HTTP** (remote) transport rather than a local/stdio command, and that it's pointed at `https://mcp.tess.im` directly (no extra path).
  </Accordion>

  <Accordion title="401 / 'unauthorized' errors">
    Both headers are required on every request — `Authorization: Bearer YOUR_API_TOKEN` and `x-workspace-id: YOUR_WORKSPACE_ID`. There is no URL query-parameter option; confirm your client supports setting custom headers, and that the token is active in the dashboard.
  </Accordion>

  <Accordion title="404 or 'workspace' errors">
    The workspace ID is missing, malformed, or the token doesn't have access to it. Confirm the `x-workspace-id` header is set and matches a workspace your token can access.
  </Accordion>

  <Accordion title="An agent fails to run">
    Some agents require specific inputs. Chat-type agents, for example, expect a `messages` array in `body`. Ask the assistant to inspect the agent's fields ([`get_agent`](#get-agent)), or check the agent in the Tess platform.
  </Accordion>
</AccordionGroup>

## Resources

* [Model Context Protocol — official site](https://modelcontextprotocol.io)
* [How to create an API Token in Tess AI](https://docs.tess.im/api/get-started/quickstart)