MCP Server - Tess AI Docs

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.

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

Why connect through MCP

Use Tess where your team already works

Run Tess agents from inside Claude, Cursor, Codex, or your own internal tools — no context switching, no copy-paste.

Zero install, always up to date

A managed endpoint maintained by Tess. New capabilities appear automatically; there is no client to upgrade.

Governed by your workspace

Every call runs with the caller’s own API token and workspace, inheriting your existing roles, permissions, and credit limits.

Standard & portable

Built on the open Model Context Protocol. The same endpoint works across every MCP-compatible platform — no per-vendor integration.

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.

Domain	Tools
Agents	`list_agents` · `get_agent` · `execute_agent` · `list_files_agent` · `link_files_agent` · `delete_file_link_agent` · `list_agent_responses` · `get_agent_response` · `list_agent_webhooks` · `create_agent_webhook` · `agent_chat_completions`
Files	`list_files` · `upload_file` · `get_file` · `delete_file` · `process_file` · `resolve_durable_file_reference`
Memories	`list_memories` · `create_memory` · `update_memory` · `delete_memory` · `import_memories_text` · `get_memory_import_status_result`
Webhooks	`list_webhooks` · `delete_webhook`
Credits & workspace	`deduct_credits_user` · `get_workspace_usage`

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.

Before you start

You need two things from the Tess platform:

Your API token

Generate a personal access token in Tess AI → API Tokens. This is the same token used across the Tess API — see Quickstart for details.

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.

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.

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. There is no query-parameter fallback — your MCP client must support setting custom headers on the connection.

Connect your platform

Claude Code
Cursor / VS Code
Codex CLI
Claude Desktop / ChatGPT / other

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.”

Add Tess to your MCP configuration (in Cursor: Tools & Integrations → MCP Tools, or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "tess": {
      "url": "https://mcp.tess.im",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN",
        "x-workspace-id": "YOUR_WORKSPACE_ID"
      }
    }
  }
}

Add a remote MCP server with headers in ~/.codex/config.toml:

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

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.

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.

How authentication works

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

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

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

Identity & permissions

Calls run with the token owner’s identity. Agent visibility, roles, and feature permissions are enforced by Tess, not bypassed.

Workspace isolation

Every request is bound to the x-workspace-id you send. One token cannot reach another workspace’s data.

Credit governance

Executions consume credits under your existing workspace limits and billing — the same as the Tess API.

Revocable access

Revoke a token in the dashboard to instantly cut off any connected platform using it. No redeploy needed.

Tools reference

list_agents

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

string

Search agents by title, description, and long description.

type

string

Filter by agent type.

page

integer

default:"1"

Page number for pagination.

per_page

integer

default:"15"

Number of agents per page.

get_agent

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

string | integer

required

The agent ID.

execute_agent

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

string | integer

required

The agent ID.

body

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).

wait_execution

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.

list_files_agent

Gets a list of files associated with a specific agent.

agentId

integer

required

ID of the agent to retrieve files for.

link_files_agent

Associates one or more files with a specific agent.

agentId

integer

required

ID of the agent to link files to.

file_ids

integer[]

required

Array of file IDs to link to the agent.

delete_file_link_agent

Removes the association between a specific file and an agent.

agentId

integer

required

ID of the agent to remove the file link from.

fileId

integer

required

ID of the file to unlink from the agent.

list_agent_responses

Lists agent execution responses, with filtering and pagination.

string

Search agents by title.

root_id

integer

Filter by root execution ID.

agent_id

integer

Filter by agent ID.

type

string

Filter by agent type.

sort

string

default:"asc"

Sort by ascending or descending (asc/desc).

page

integer

default:"1"

Current page.

per_page

integer

default:"15"

Number of items per page.

get_agent_response

Fetches a single agent execution response by ID.

string | integer

required

The agent execution ID.

list_agent_webhooks

Lists webhooks registered for a specific agent.

integer

required

Agent ID.

page

integer

default:"1"

Current page.

per_page

integer

default:"15"

Number of items per page.

create_agent_webhook

Registers a new webhook on a specific agent.

string | integer

required

The agent ID.

url

string

The webhook target URL.

method

string

default:"POST"

HTTP method used for the webhook call.

status

string

default:"active"

Webhook status (active/inactive).

agent_chat_completions

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

string | integer

required

The agent ID.

body

object

required

An OpenAI Chat Completions-shaped request body.

list_files

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

page

integer

default:"1"

Page number for pagination.

per_page

integer

default:"15"

Number of items per page (max 100).

order

string

default:"desc"

Sort order for the created_at field (asc/desc).

upload_file

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

file

binary

required

The file to upload.

process

boolean

default:"false"

Whether to process the file immediately after upload.

get_file

Returns the details of a single file.

fileId

integer

required

The file ID.

delete_file

Deletes a file from the workspace.

fileId

integer

required

The file ID.

process_file

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

fileId

integer

required

The file ID.

resolve_durable_file_reference

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.

ref

string

required

The durable artifact reference to resolve.

list_memories

Lists memories stored in the workspace.

collection_id

integer

Filter by memory collection.

page

integer

default:"1"

Page number for pagination.

per_page

integer

default:"10"

Items per page (max 50).

create_memory

Saves a new memory to a collection.

collection_id

integer

The memory collection to store the memory in.

memory

string

The memory text to store (max 32,000 characters).

update_memory

Edits an existing memory.

memory_id

integer

required

The memory to update.

memory

string

New memory text.

collection_id

integer

Move the memory to a different collection.

delete_memory

Removes an existing memory.

memory_id

integer

required

The memory to delete.

import_memories_text

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

wait

boolean

default:"false"

Whether to block until the import completes (bounded timeout) instead of returning immediately.

get_memory_import_status_result

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

string | integer

required

The import execution ID.

list_webhooks

Lists all webhooks in the workspace.

page

integer

default:"1"

Current page.

per_page

integer

default:"15"

Number of items per page.

delete_webhook

Deletes a webhook by ID.

integer

required

The webhook ID.

deduct_credits_user

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.

tess_external_identifier

integer

required

Identifier for the user/workspace whose credits will be deducted.

resource_type

string

required

Type of resource being metered (e.g. image).

resource_amount

number

required

Positive numeric value used for the credit calculation.

workspace_id

integer

The workspace ID.

resource_id

string

ID of the resource being metered.

inputs

object

Additional inputs for the credit calculation.

get_workspace_usage

Returns workspace usage broken down by type and date range.

range

string

Preset date range filter (1d/7d/30d).

start_date

string

Custom start date (YYYY-MM-DD). Use with end_date; overrides range.

end_date

string

Custom end date (YYYY-MM-DD). Use with start_date; overrides range.

user_id

integer

Filter by user ID (requires the WORKSPACE_DOCUMENTS_READ permission).

type

string

Filter by usage type (chat, image, text, tool_execution, connector_calls, and more).

page

integer

default:"1"

Page number for pagination.

Example: run an agent end to end

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

Discover agents

“List my Tess agents” → the assistant calls list_agents and shows what’s available.

Capture context as memory

“Save to my ‘Engineering Standards’ collection: always write unit tests with BDD” → create_memory.

Run an agent

“Use the Code Review agent to review this function, and wait for the result” → execute_agent returns the output inline.

Reuse later

“List my memories” → list_memories confirms what’s stored for future runs.

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

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).

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.

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.

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), or check the agent in the Tess platform.

​Why connect through MCP

Use Tess where your team already works

Zero install, always up to date

Governed by your workspace

Standard & portable

​What the server exposes

​Before you start

​Authenticating

​Connect your platform

​How authentication works

Identity & permissions

Workspace isolation

Credit governance

Revocable access

​Tools reference

​list_agents

​get_agent

​execute_agent

​list_files_agent

​link_files_agent

​delete_file_link_agent

​list_agent_responses

​get_agent_response

​list_agent_webhooks

​create_agent_webhook

​agent_chat_completions

​list_files

​upload_file

​get_file

​delete_file

​process_file

​resolve_durable_file_reference

​list_memories

​create_memory

​update_memory

​delete_memory

​import_memories_text

​get_memory_import_status_result

​list_webhooks

​delete_webhook

​deduct_credits_user

​get_workspace_usage

​Example: run an agent end to end

​Governance & compliance

​Troubleshooting

​Resources

Why connect through MCP

What the server exposes

Before you start

Authenticating

Connect your platform

How authentication works

Tools reference

list_agents

get_agent

execute_agent

list_files_agent

link_files_agent

delete_file_link_agent

list_agent_responses

get_agent_response

list_agent_webhooks

create_agent_webhook

agent_chat_completions

list_files

upload_file

get_file

delete_file

process_file

resolve_durable_file_reference

list_memories

create_memory

update_memory

delete_memory

import_memories_text

get_memory_import_status_result

list_webhooks

delete_webhook

deduct_credits_user

get_workspace_usage

Example: run an agent end to end

Governance & compliance

Troubleshooting

Resources