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.
Authenticating
Credentials are sent as HTTP headers only — never as URL query parameters, so tokens don’t end up in logs or browser history:Connect your platform
- Claude Code
- Cursor / VS Code
- Codex CLI
- Claude Desktop / ChatGPT / other
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:- 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.
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.
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 theirmission-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.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 durabledoc://<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
The client connects but no tools appear
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.404 or 'workspace' errors
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
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

