#MCP tools

The Tessl MCP (Model Context Protocol) server provides tools that AI coding agents can use to search for, install, and work with plugins from the Tessl registry.

#Registry MCP server vs. MCP gateway

Tessl exposes MCP through two distinct entry points — pick the one that matches what you need:

• Registry MCP server (tessl mcp start): a local stdio server that gives the agent the tools listed on this page. They cover authentication, registry search, plugin install and update, workspace management, publishing, and skill review. Use it when the agent needs to discover and manage Tessl plugins. This is the server tessl init configures for auto-detected agents.
• MCP gateway (tessl mcp proxy <workspace>/<mcp>): a stdio proxy that connects the agent to an external MCP server through a workspace. Use it when several teammates need to share access to an upstream MCP server (such as a third-party integration) without each person re-running its OAuth flow. See MCP gateway for how organization admins register servers and which ones the proxy reaches.

The rest of this page documents the tools exposed by the registry MCP server.

#Server Configuration

The Tessl MCP server can be configured in your AI coding agent's MCP configuration or by running:

tessl init --agent <agent-name>

Server Details:

• Command: tessl mcp start
• Type: stdio
• Name: Tessl Registry MCP

#Available Tools

The registry MCP server exposes 27 tools:

Tools marked "Required" start the browser authentication flow automatically if you call them while signed out. Tools marked "Not required" work without being signed in, though search and install may return a hint suggesting login when missing credentials limit their results: they never trigger the sign-in flow themselves.

#login

Authenticate with Tessl to access registry features.

Authentication: Not required (this tool provides authentication)

Parameters

None

Notes

• Attempts to open authentication URL in your browser automatically
• Authentication happens asynchronously - credentials are saved in the background
• After completing authentication once, authenticated tools work automatically
• Triggers automatic dependency sync after successful login

#search

Search for plugins in the Tessl registry by name, package URL (PURL), or HTTP URL.

Authentication: Not required. If you are signed out, results are limited to public plugins and the response includes a hint suggesting login

Parameters

• query (string, required): Search query - can be a plugin name, package URL, or HTTP URL

Notes

• Works with partial names and package URLs (PURLs)
• Supports HTTP URLs from package registries (e.g., npm, PyPI)
• Returns plugin name, version, description, and installation command

Example

{
  "query": "svelte"
}

#install

Install plugins into your project. Can install a specific plugin or sync all missing plugins from tessl.json.

Authentication: Not required. If you are signed out, only public plugins can be installed

Parameters

• packageName (string, optional): plugin name to install (e.g., "workspace/plugin" or "workspace/plugin@version"). If not provided, installs all missing plugins from tessl.json
• projectDir (string, optional): Project directory. Defaults to the tessl project found by walking up from the MCP server's working directory. Required if no project is found. Only used when packageName is also supplied, in which case supplying it creates a new tessl project at that path. Without packageName, the sync writes nothing to disk if there are no plugins to add or remove
• skills (string array, optional): Skill names to install, for a source that exposes selectable skills (a GitHub repository with several skills, or a registry plugin skill). If omitted for such a source, the tool lists the available skills instead of installing

Notes

• plugins are installed to .tessl/plugins/<workspace>/<plugin>/ in your project
• Your project's tessl.json is automatically updated with the plugin reference
• If a plugin is already installed and up-to-date, it will be skipped
• If no version is specified, installs the latest version
• packageName also accepts a GitHub source (https://github.com/user/repo or github:user/repo). For a repository with several skills, pass skills. The tool lists the available skills if you omit it

Example: Install specific plugin

{
  "packageName": "tessl/svelte@5.38.0"
}

Example: Sync all missing plugins

{}

#uninstall

Uninstall a plugin from your project.

Authentication: Not required

Parameters

• packageName (string, required): plugin name to uninstall (e.g., "workspace/plugin"). Also accepts a source such as file:path/to/plugin
• skills (string array, optional): Specific skills to remove instead of the whole plugin. If every skill is removed, the plugin is uninstalled

Notes

• Removes the plugin from tessl.json and deletes files from .tessl/plugins/
• Does not require authentication (local operation only)
• Only affects your local project - doesn't unpublish from the registry

Example

{
  "packageName": "tessl/svelte"
}

#outdated

Check which installed plugins have newer versions available in the registry.

Authentication: Not required

Parameters

• projectDir (string, optional): Project directory to check. Defaults to the tessl project found by walking up from the MCP server's working directory

Notes

• Reports only. It does not change any installed plugin
• Use update to apply the newer versions it lists

Example

{
  "projectDir": "./my-app"
}

#update

Update named plugins to newer versions.

Authentication: Not required

Parameters

• tiles (string array, required): plugin names to update (e.g., ["engteam/svelte"]). At least one name is required
• force (boolean, optional): Include breaking updates. Defaults to false

Notes

• There is no "update everything" form. Name the plugins you want changed
• Without force, updates that cross a major version are skipped

Example

{
  "tiles": ["engteam/svelte"],
  "force": false
}

#status

Check authentication status and plugin synchronization status for your project.

Authentication: Not required

Parameters

None

Notes

• Returns JSON with authentication status and plugin sync summary
• Shows plugins that are up-to-date, missing, outdated, or invalid
• Useful for checking if you need to run tessl install to sync plugins

Example

{                                                                     
       "authentication": {
         "authenticated": true,
         "email": "example@tessl.io"
       },
       "manifest": {
         "summary": {
           "upToDate": 1,
           "missing": 0,
           "outdated": 0,
           "invalid": 0
         },
         "tiles": {
           "upToDate": [
             {
               "workspaceName": "tessl",
               "tileName": "pypi-fastapi",
               "manifestVersion": "0.116.0",
               "installedVersion": "0.116.0"
             }
           ],
           "missing": [],
           "outdated": [],
           "invalidPackages": []
         }
       }
     }

#skills_available

List the installable skills across the workspaces you are a member of.

Authentication: Required

Parameters

• workspace (string, optional): Filter results to a single workspace by name or ID

Notes

• Each result includes the name, version, description, and an installation reference you can pass straight to install
• Use it to see what your team already publishes before you scaffold something new
• Without workspace, the tool queries every workspace you belong to at once. If any one of those queries fails, the whole call fails. Pass workspace to scope the call to a single workspace and make retries cheaper

Example

{
  "workspace": "engteam"
}

#workspace_list

List all workspaces that you are a member of.

Authentication: Required

Parameters

None

Notes

• Returns the workspace name and ID for each membership
• Use the ID with workspace_list_members, or as the workspace argument to the publish tools

Example

{}

#workspace_list_members

List all members of a workspace.

Authentication: Required

Parameters

• workspace (string, required): Name or ID of the workspace to list members for

Example

{
  "workspace": "engteam"
}

#workspace_create

Create a new workspace.

Authentication: Required

Parameters

• name (string, required): Name of the workspace to create (1-100 characters)
• orgId (string, optional): ID of the organization to create the workspace in

Notes

• Without orgId, the workspace is created in your default organization

Example

{
  "name": "engteam"
}

#new_plugin

Scaffold a new plugin, generating the files you then edit to add the context you want.

Authentication: Required

Parameters

• name (string, required): plugin name in workspace/plugin-name format
• summary (string, required): Brief description of the plugin
• path (string, optional): Directory to create the plugin in. Defaults to plugins/{plugin-name}
• rules (string or object, optional): Rule name to create. The object form takes name and an optional description holding the initial rule instructions
• skill (object, optional): Skill to include, with name and description
• isPrivate (boolean, optional): Make the plugin private. Defaults to true

Notes

• You must pass at least one of skill or rules. A plugin with neither has no content to generate

Example

{
  "name": "engteam/svelte",
  "summary": "Svelte 5 conventions for our apps",
  "skill": {
    "name": "svelte-runes",
    "description": "How to use runes for reactive state"
  }
}

#tile_publish

Publish a plugin directory to the Tessl registry and return the registry URL.

Authentication: Required

Parameters

• path (string, optional): Path to the plugin directory to publish. Defaults to the current directory
• workspace (string, optional): Workspace name override

Notes

• Requires an existing manifest in the directory, and never changes its visibility. Use skill_publish to publish a skill that has no manifest yet
• Auto-bumps the patch version on collision, so you do not manage versions yourself
• Skips eval publishing. Use the CLI for evals

Example

{
  "path": "plugins/svelte"
}

#skill_publish

Publish a skill directory to the Tessl registry and return the registry URL.

Authentication: Required

Parameters

• path (string, optional): Path to the skill directory to publish. Defaults to the current directory
• workspace (string, optional): Workspace to create the manifest under when the skill has neither a tile.json nor a plugin.json yet. Ignored when either manifest already exists, since its name decides the destination workspace
• public (boolean, optional): Make the skill publicly visible in the registry. Defaults to private

Notes

• Auto-bumps the patch version on collision
• Skips eval publishing. Use the CLI for evals

Example

{
  "path": "plugins/svelte/skills/svelte-runes",
  "workspace": "engteam"
}

#review_run

Start an asynchronous review of a skill.

Authentication: Required

Parameters

• path (string, optional): Path to a skill file or skill directory. Defaults to the current directory
• workspace (string, optional): Workspace name or ID. Resolved automatically when not provided
• kind (string, optional): quality for a skill quality review, or security for a security findings review. Defaults to quality

Notes

• Returns a run ID immediately. Poll review_view for the result
• Quality reviews (kind: "quality") and security reviews (kind: "security") are both free. Call it once per user action. review_view reports the actual charge once the run finishes

Example

{
  "path": "plugins/svelte/skills/svelte-runes",
  "kind": "quality"
}

#review_fix

Start an asynchronous skill-improvement fix run.

Authentication: Required

Parameters

• path (string, optional): Path to a skill file or skill directory. Defaults to the current directory
• workspace (string, optional): Workspace name or ID. Resolved automatically when not provided
• threshold (number, optional): Stop improving once the review score reaches this percentage (0-100). Defaults to the server default
• maxIterations (number, optional): Maximum number of improve-then-review iterations (1-10). Defaults to the server default

Notes

• Returns a fix run ID immediately, and writes nothing locally
• When the run completes, call review_view with apply: true and the skill path to write the improved skill back. This is the equivalent of tessl review fix --yes
• A fix run consumes credits. Call it once per user action

Example

{
  "path": "plugins/svelte/skills/svelte-runes",
  "threshold": 90
}

#review_view

Fetch the current status and results for a review run or a fix run.

Authentication: Required

Parameters

• runId (string, required): The run ID returned by review_run, or the fix run ID returned by review_fix
• apply (boolean, optional): Fix runs only. When true, writes the completed fix run's improved skill back to the local files. Defaults to false, which reports the score and summary and changes nothing on disk
• path (string, optional): Fix runs only, paired with apply. Path to the local skill file or directory to write the improvement into. Defaults to the current directory. Use the same skill the fix run was started against

Notes

• Poll until status is completed, failed, or cancelled. These are the only terminal states
• Review and fix runs typically take from tens of seconds to a few minutes. Poll every 5-10 seconds rather than continuously

Example

{
  "runId": "run_01j9x2c8",
  "apply": true,
  "path": "plugins/svelte/skills/svelte-runes"
}

#project_list

List all projects in a workspace.

Authentication: Required

Parameters

• workspace (string, required): Name or ID of the workspace to list projects for

Example

{
  "workspace": "engteam"
}

#schedule_create

Create a scheduled run that fires a launch run on a cron. Provide either fromRun (to copy an existing run's config) or skill + repo + environment (inline spec).

Authentication: Required

Parameters

• cron (string, required): Cron expression the schedule fires on (5-field standard cron, e.g. "0 9 * * 1-5")
• timezone (string, optional): IANA timezone the cron is interpreted in. Defaults to UTC
• fromRun (string, optional): Launch run ID whose config this schedule copies. Mutually exclusive with all inline launch-spec fields (skill, repo, baseBranch, cwd, agent, model, environment, instructions)
• skill (string, optional): Skill to run, as workspace/plugin[@version][#skill] or file:path/to/plugin[#skill], a path from the directory of the project's tessl.json. Required without fromRun
• repo (string, optional): Target repository as owner/name or URL. Required without fromRun
• baseBranch (string, optional): Branch to clone and target the PR against. Defaults to the project or repository default
• cwd (string, optional): Subdirectory to run the skill in, relative to the repo root
• agent (string, optional): Agent to run the skill with (selects the cloud strategy)
• model (string, optional): Model to use for each run (e.g. claude-opus-4-6)
• environment (string, optional): Name or ID of workspace environment whose variables are made available to each run. Required for inline schedules
• inputs (object, optional): Skill input values as a map of string keys to string values (e.g. { "KEY": "value" }). Both keys and values must be strings
• instructions (string, optional): Instructions to append to the skill prompt
• workspace (string, optional): Workspace name or ID to schedule in. Resolved in order: explicit input, TESSL_WORKSPACE env var, workspace linked to the current directory via tessl init. Required if none of those apply
• label (string, optional): Label to describe this schedule

Example

{
  "cron": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "skill": "engteam/daily-checks",
  "repo": "myorg/myrepo",
  "environment": "prod",
  "workspace": "engteam"
}

#schedule_list

List scheduled runs. Returns id, status, cron, workspace, and next/last run time for each schedule.

Authentication: Required

Parameters

• workspace (string, optional): Filter by workspace name or ID
• status (string, optional): Filter by status: active or paused
• limit (positive integer, optional): Maximum number of schedules to return. Defaults to 20

Example

{
  "workspace": "engteam",
  "status": "active"
}

#schedule_view

View config, triggers, and next/last run for a scheduled run.

Authentication: Required

Parameters

• id (string, required): Scheduled run ID

Example

{
  "id": "018e1d4e-6153-7000-b00f-000000000001"
}

#schedule_runs

List the launch runs a scheduled run has spawned, newest first. Returns status, timestamps, and liveness for each run. The result is bounded: the backend returns at most 100 runs and there is no cursor for older pages.

Authentication: Required

Parameters

• id (string, required): Scheduled run ID (UUID)
• limit (positive integer, optional): Maximum number of launch runs to return. Defaults to 20, maximum 100

Example

{
  "id": "018e1d4e-6153-7000-b00f-000000000001",
  "limit": 10
}

#schedule_pause

Pause a scheduled run so it stops firing. Use schedule_resume to re-enable it.

Authentication: Required

Parameters

• id (string, required): Scheduled run ID

Example

{
  "id": "018e1d4e-6153-7000-b00f-000000000001"
}

#schedule_resume

Resume a paused scheduled run so it fires again on its cron.

Authentication: Required

Parameters

• id (string, required): Scheduled run ID

Example

{
  "id": "018e1d4e-6153-7000-b00f-000000000001"
}

#schedule_update

Update a scheduled run's cron, timezone, or label. At least one of cron, timezone, or label is required.

Authentication: Required

Parameters

• id (string, required): Scheduled run ID
• cron (string, optional): New cron expression (5-field standard cron)
• timezone (string, optional): New IANA timezone the cron is interpreted in (e.g. UTC, America/New_York)
• label (string, optional): New label to describe this schedule

Example

{
  "id": "018e1d4e-6153-7000-b00f-000000000001",
  "cron": "0 10 * * 1-5",
  "timezone": "Europe/London"
}

#schedule_trigger

Fire a scheduled run immediately, out of band (independent of its cron), optionally as one of its cron triggers. Returns the schedule's status.

Authentication: Required

Parameters

• id (string, required): Scheduled run ID
• triggerName (string, optional): Name of one of the schedule's cron triggers to run as. The run uses that trigger's overrides. Omit it to run the schedule's own action.

Example

{
  "id": "018e1d4e-6153-7000-b00f-000000000001",
  "triggerName": "weekly"
}

#schedule_delete

Permanently delete a scheduled run. This cannot be undone.

Authentication: Required

Parameters

• id (string, required): Scheduled run ID

Example

{
  "id": "018e1d4e-6153-7000-b00f-000000000001"
}