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.

Tess MCP Server

This page. Expose Tess agents, files, and memories to Claude, Cursor, Codex, or any MCP client.

Custom MCP

The other direction: connect external MCP servers into Tess chat and agents, with personal or shared scope.

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 an explicit allow-list of the public Tess API — the same endpoints documented in API Overview. New API capabilities appear as MCP tools only after they are added to that public surface. 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` · `get_agent_response` · `list_agent_webhooks` · `create_agent_webhook`
Files	`list_files` · `upload_file` · `get_file` · `delete_file` · `process_file`
Memories	`list_memories` · `create_memory` · `update_memory` · `delete_memory`
Memory collections	`list_memory_collections` · `create_memory_collection` · `update_memory_collection` · `delete_memory_collection`
Webhooks	`list_webhooks` · `delete_webhook`
Workspace and audit	`get_workspace_usage` · `list_audit_events`

The list matches the public API. Internal session-only endpoints are never exposed as MCP tools. Ask your assistant to list available tools if you want to confirm the live set from your client.

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

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.”Remote JSON configs need type set to http (or streamable-http). A url without type is skipped as a broken stdio server.

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"
      }
    }
  }
}

Prefer interpolating an environment variable for the token instead of saving it in plaintext. Cursor resolves env interpolation in url and headers.

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.

get_agent

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

execute_agent

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

list_files_agent

Gets a list of files associated with a specific agent.

link_files_agent

Associates one or more files with a specific agent.

delete_file_link_agent

Removes the association between a specific file and an agent.

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.

integer

default:"1"

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

string

The webhook target URL.

string

default:"POST"

HTTP method used for the webhook call.

string

default:"active"

Webhook status (active/inactive).

list_files

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

integer

default:"1"

Page number for pagination.

integer

default:"15"

Number of items per page (max 100).

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.

binary

required

The file to upload.

boolean

default:"false"

Whether to process the file immediately after upload.

get_file

Returns the details of a single file.

integer

required

The file ID.

delete_file

Deletes a file from the workspace.

integer

required

The file ID.

process_file

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

integer

required

The file ID.

list_memories

Lists memories stored in the workspace.

integer

Filter by memory collection.

integer

default:"1"

Page number for pagination.

integer

default:"10"

Items per page (max 50).

create_memory

Saves a new memory to a collection.

integer

The memory collection to store the memory in.

string

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

update_memory

Edits an existing memory.

integer

required

The memory to update.

string

New memory text.

integer

Move the memory to a different collection.

delete_memory

Removes an existing memory.

integer

required

The memory to delete.

list_memory_collections

Lists memory collections in the workspace.

string

Filter collections by name.

integer

default:"1"

Page number.

integer

default:"12"

Items per page (1–50).

create_memory_collection

Creates a memory collection.

string

required

Collection name.

string

Optional description.

update_memory_collection

Updates a memory collection.

integer

required

The collection to update.

string

New name.

string

New description.

delete_memory_collection

Deletes a memory collection.

integer

required

The collection to delete.

list_webhooks

Lists all webhooks in the workspace.

integer

default:"1"

Current page.

integer

default:"15"

Number of items per page.

delete_webhook

Deletes a webhook by ID.

integer

required

The webhook ID.

get_workspace_usage

Returns workspace usage broken down by type and date range.

string

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

string

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

string

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

integer

Filter by user ID (requires the WORKSPACE_DOCUMENTS_READ permission).

string

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

integer

default:"1"

Page number for pagination.

list_audit_events

Pulls workspace-scoped audit events for SIEM ingestion. The time window is required and cannot exceed 30 days.

string

required

Start of the time window (YYYY-MM-DD).

string

required

End of the time window (YYYY-MM-DD). Must be within 30 days of from.

integer

default:"50"

Max events per page (1–200).

string

Opaque pagination cursor from a previous response.

string

Filter by source (auditable or activity).

string

Filter by event type.

integer

Filter by actor.

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). In Claude Code, remote JSON entries also need type set to http.

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.

Resources

Custom MCP — connect external MCP servers into Tess
Sharing and permissions
MCP best practices
Model Context Protocol — official site
How to create an API Token in Tess AI

Tess MCP Server

Custom MCP

​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

​get_agent_response

​list_agent_webhooks

​create_agent_webhook

​list_files

​upload_file

​get_file

​delete_file

​process_file

​list_memories

​create_memory

​update_memory

​delete_memory

​list_memory_collections

​create_memory_collection

​update_memory_collection

​delete_memory_collection

​list_webhooks

​delete_webhook

​get_workspace_usage

​list_audit_events

​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

get_agent_response

list_agent_webhooks

create_agent_webhook

list_files

upload_file

get_file

delete_file

process_file

list_memories

create_memory

update_memory

delete_memory

list_memory_collections

create_memory_collection

update_memory_collection

delete_memory_collection

list_webhooks

delete_webhook

get_workspace_usage

list_audit_events

Example: run an agent end to end

Governance & compliance

Troubleshooting

Resources