Skip to main content
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.
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:
1

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

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

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.

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:

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. Associates one or more files with a specific 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.
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.

get_mission_control_usage

Returns the workspace’s AI consumption, executions and adoption for a period, bucketed in the given timezone and optionally grouped, filtered and compared with the previous period. Same query and permissions as the Mission Control panel: the caller only sees their own usage, their team’s or the whole workspace, according to their mission-control:* permissions. Full parameter and response reference: Mission Control usage.
string
required
Start of the period, local date (YYYY-MM-DD).
string
required
End of the period, local date (YYYY-MM-DD), inclusive. The period is at most 93 days.
string
IANA timezone the dates and buckets are read in (default: the platform timezone).
string
default:"day"
Bucket size of the series: hour, day, week or month. Use month for overviews.
string[]
Dimensions to group by, at most 3: agent, person, resource, resource_kind, execution_type, modality, activity_category, charge_type, execution_origin, trigger_source, agent_origin. Grouping by person needs mission-control:person-data:view.
string[]
Person aliases (me, my_team, my_workspace) or person ids taken from a previous answer grouped by person. Never guess ids.
integer[]
Team ids from scope.teams of a previous answer.
integer[]
Agent ids from a previous answer grouped by agent.
string[]
model, tool, connector, upload, kb, memory, voice or other. Combine with group_by[]=resource for “consumption per model”.
string
previous_period or previous_calendar_month: adds the previous period’s totals and the delta.
string
Metric id to order the groups by (default: the first requested metric). sort_by (value, delta_abs, delta_pct) and order (desc, asc) refine it.
integer
default:"50"
Groups per page (1–200). Keep it at 10 or less in a conversation: the answer carries a zero-filled series per group.
string
Opaque pagination cursor from page.next_cursor of a previous answer.
Refusals reach the assistant as the tool error with the API body: query refusals carry a stable code (window_too_large, no_team, person_data_not_allowed, usage_rollup_disabled, …), access refusals carry only message. Example prompt: “How much did we spend per model this month?” → the assistant calls the tool with from/to covering the month, group_by[]=resource, filters[resource_kind][]=model, granularity=month and limit=10, then reads groups[].totals.consumption_net.

list_agent_versions

Returns a paginated list of published versions for an agent. Requires the agent:version:read permission. Each item includes change_summary and diff vs the immediately previous published version (API field names). Full reference: List Agent Versions.

get_agent_version

Returns the full details (including snapshot) of a specific agent version. Requires the agent:version:read permission. Full reference: Get Agent Version.

rollback_agent_version

Creates a new published version by restoring the snapshot of the target version, making it the active version. Requires access to edit the agent. Full reference: Rollback Agent Version.

list_all_schedulers

Returns a paginated list of all schedulers for the authenticated user. Full reference: List All Schedulers.

list_agent_schedulers

Returns a paginated list of schedulers for a specific agent. Full reference: List Agent Schedulers.

create_agent_scheduler

Creates a new scheduler for a specific agent. Full reference: Create Scheduler.

get_agent_scheduler

Returns a single scheduler with next_run information. Full reference: Get Scheduler.

update_agent_scheduler

Updates an existing scheduler. Full reference: Update Scheduler.

delete_agent_scheduler

Soft-deletes a scheduler. Full reference: Delete Scheduler.

delete_scheduler_by_root_execution

Soft-deletes all schedulers that belong to the authenticated user, the given agent, and the given agent_root_id_execution within the current workspace. Full reference: Delete Schedulers by Root Execution.

list_artifacts

Artifacts the token user created in the workspace, newest first. Paginated without a total: meta.has_more tells whether another page exists. Full reference: List Artifacts.

create_artifact

Renders a new HTML artifact (version 1) from a template. Needs the artifact feature, a plan that includes artifacts and the Artifacts User permission (artifacts:create). Full reference: Create Artifact.

read_artifact

The head version with its HTML. Holders of the Artifacts Manager permission (artifacts:manage) may also read other members’ artifacts of the workspace, read-only; that read is audited. Full reference: Get Artifact.

rename_artifact

Changes the title. No new version is written: a shared version keeps the title it was published with until a newer version is published. Full reference: Rename Artifact.

delete_artifact

Soft-deletes the artifact, removes it from its chat and unpublishes it: its viewer, grants and public link stop working at once. Needs the Artifacts User permission (artifacts:create) and the workspace content-deletion permission (governance:content:delete). Full reference: Delete Artifact.

edit_artifact

Applies patch operations to the head and writes a new version. Operations: replace (old, new), insert_before/insert_after (anchor, text), replace_range (from, to, new), prepend/append (text), and selector operations on one element of the content region: set_text (selector, text), replace_element (selector, html), set_attribute (selector, name, value), remove_element (selector). Anchors and selectors must match exactly once. Send base_version to get 409 ARTIFACT_STALE instead of editing a newer head. Full reference: Edit Artifact.

publish_artifact_version

Makes one version (default: the head) the shared version that grants open. Who can open it is set with the share endpoint. Full reference: Publish Artifact Version.

unpublish_artifact

Ends the active publication: no version is shared any more, and every access grant (people, teams, workspace and the public link) is deleted, so nobody but the owner and holders of the Artifacts Manager permission can open it. Sharing again starts fresh: the first grant publishes the latest version. Allowed to the owner, who may publish again later, and to holders of the Artifacts Manager permission (artifacts:manage) in the artifact’s workspace, whose unpublish the owner cannot undo. Full reference: Unpublish Artifact.

restore_artifact_version

Writes an earlier version again as the new head; history is kept. The restored head is not shared until published. Full reference: Restore Artifact Version.

share_or_unshare_artifact

Grants and revokes access in one all-or-nothing call. Granting needs the Artifacts User permission (artifacts:create) and stays within the sharer’s sharing restrictions, set on the Members page: the member’s own restriction, else the most permissive of their teams’, else the defaults (organization, workspace and teams on; public off). Targets: {type: user, user_id|email} (a person of this workspace needs the workspace level; a person from another workspace of the same organization needs the organization level, which exists only when the workspace belongs to one), {type: team, team_id} (only a team the sharer belongs to), {type: workspace}, {type: public}. The first grant publishes the head when nothing is shared yet. public (anyone with the link) opens for any signed-in Tess user, from any organization; anonymous visitors are sent to login first. Full reference: Share or Unshare Artifact.

list_artifact_versions

Version history, newest first, with the head and the shared (published) version marked. Full reference: List Artifact Versions.

delete_one_artifact_version

Deletes one version; its number is never reused. Deleting the head makes the newest remaining version the head. Deleting the shared version shares the newest remaining earlier version instead, or, with none earlier, stops sharing. The only remaining version cannot be deleted this way (422 ARTIFACT_LAST_VERSION): delete the artifact instead. Full reference: Delete Artifact Version.

list_artifact_templates

Templates new artifacts can be created from in this workspace: the global ones plus the workspace’s own (which win by slug). Full reference: List Artifact Templates.

import_memories_text

Triggers memory import from free text. Async by default; optionally wait for completion with ?wait=true. Full reference: Import Memories from Text.

get_memory_import_status_result

Returns the status and summary for an import execution. Full reference: Get Memory Import Status.

list_digital_employee_capabilities

Returns the effective capability map for the current user in the workspace. Full reference: Get Capabilities.

list_digital_employees

Returns a paginated list of all digital employees in the workspace. Full reference: List Digital Employees.

create_standalone_digital_employee

Creates a new Digital Employee with a new host agent. Full reference: Create Standalone Employee.

create_digital_employee_agent

Creates a new Digital Employee linked to an existing agent. Full reference: Create Employee from Agent.

get_digital_employee

Returns a single digital employee with its main relations. Full reference: Get Digital Employee.

update_digital_employee

Updates one or more fields of an existing digital employee. Full reference: Update Digital Employee.

duplicate_digital_employee

Creates a copy of an existing digital employee. Full reference: Duplicate Digital Employee.

delete_digital_employee

Soft-deletes a digital employee. The employee can be recovered. Full reference: Delete Digital Employee.

preview_digital_employee_schedule

Validates a schedule definition and returns the next planned occurrences. Full reference: Preview Schedule.

invoke_digital_employee

Triggers a manual run of a digital employee. Full reference: Invoke Digital Employee.

retry_digital_employee_run

Re-executes a finished run of a digital employee. Full reference: Retry Run.

list_digital_employee_runs

Returns a paginated list of execution runs for a digital employee. Full reference: List Runs.

get_digital_employee_run

Returns the details of a specific run. Full reference: Get Run.

get_digital_employee_run_output

Returns the consolidated output of a completed run. Full reference: Get Run Output.

pause_digital_employee

Pauses a digital employee, preventing new scheduled runs from starting. Full reference: Pause Digital Employee.

resume_digital_employee

Resumes a paused digital employee, re-enabling scheduled runs. Full reference: Resume Digital Employee.

list_digital_employee_rollback_options

Returns the list of available versions to roll back to for a digital employee. Full reference: Get Rollback Options.

rollback_digital_employee

Restores a digital employee to a previous version. Full reference: Rollback Digital Employee.

reparent_digital_employee

Assigns a new parent employee, making this employee a child of another. Full reference: Reparent Digital Employee.

detach_digital_employee

Removes the parent relationship, making this employee a top-level employee. Full reference: Detach Digital Employee.

get_digital_employee_run_summary

Returns aggregated statistics about the runs of a digital employee. Full reference: Get Runs Summary.

get_digital_employee_activity

Returns the activity log for a digital employee. Full reference: Get Activity Log.

list_digital_employee_files

Returns the files associated with the most recent run of a digital employee. Full reference: Get Employee Files.

update_digital_employee_goal

Sets or updates the goal definition for a digital employee. Full reference: Update Goal.

approve_digital_employee

Approves a digital employee that is in pending_approval status. Full reference: Approve Hire Request.

reject_digital_employee

Rejects a digital employee hire request in pending_approval status. Full reference: Reject Hire Request.

upload_digital_employee_avatar

Uploads an avatar image for use with a digital employee. Full reference: Upload Avatar.

export_digital_employee_template_pack

Exports a digital employee configuration as a portable template pack. Full reference: Export Template Pack.

preview_digital_employee_template_import

Validates a template pack and returns a preview of what will be imported, including any conflicts. Full reference: Preview Template Import.

import_digital_employee_template_pack

Imports a template pack, creating or updating a digital employee from the pack configuration. Full reference: Import Template Pack.

get_me

Returns the name, e-mail, remaining credits and affiliate code of the user that owns the token. Full reference: Get Current User.

list_agent_responses

Returns a paginated list of agent executions (responses) of the workspace, newest last unless sorted. Full reference: List Agent Responses.

resolve_durable_file_reference

Resolves a durable doc://<universal_id> artifact reference into a freshly minted, short-lived signed download URL. Identity and workspace scope come from the authenticated API token and the resolved workspace context (header x-workspace-id), never from the body. Full reference: Resolve File Reference.

update_file_visibility

Sets who can see a file: only its owner, the whole workspace, or anyone with the link. Full reference: Update File Visibility.

get_memory_collection_ids

Returns a flat list of all memory collection IDs accessible by the authenticated user. Full reference: List Collection IDs.

Example: run an agent end to end

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

Discover agents

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

Capture context as memory

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

Run an agent

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

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

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