Skip to main content

Connect Your Editor via MCP

Beyond running agents, AgentMesh also exposes its own tools (managing organizations, projects, workflows, artifacts) over MCP, so you can drive the platform directly from your coding CLI or editor — Claude Code, Codex CLI, VS Code, Cursor, Antigravity — without leaving it.

1. Generate a token​

Open the account menu → MCP settings, then select Setup & Authentication:

  • Pick your organization in the top bar.
  • Enter a Name for this token (e.g. My development laptop).
  • Click Generate token.

The plaintext key is shown once — copy it now, it can't be retrieved again. Each token is tied to one org; make a separate one per machine so you can revoke individually later.

Only an organization admin can create, list, or revoke its MCP keys. A user can hold at most 10 active keys across organizations, and two active keys created by the same user in one organization cannot have the same name (case-insensitive).

2. Copy the config for your client​

Still on the Setup & Authentication tab, pick your client's icon (Claude Code, Codex CLI, VS Code, Cursor, or Antigravity) — the box below updates with a ready-to-use snippet for that client, already filled in with your token and the right endpoint. Click Copy.

Claude Code​

Run the copied command in your terminal:

claude mcp add --transport http agentmesh <your-endpoint> \
  --header "X-AgentMesh-Api-Key: <your-token>"

Then run claude mcp get agentmesh to verify, and use /mcp inside a Claude Code session to check the connection.

Codex CLI​

Paste the copied block into ~/.codex/config.toml (or .codex/config.toml for one trusted project):

[mcp_servers.agentmesh]
url = "<your-endpoint>"
http_headers = { "X-AgentMesh-Api-Key" = "<your-token>" }

Run codex mcp list, then use /mcp inside Codex to verify.

VS Code​

Create or open .vscode/mcp.json in your workspace and paste the copied JSON. Start the agentmesh server from MCP: List Servers. VS Code will prompt for the API key the first time — paste it there; it's stored as a secret input, not in the file.

Cursor​

Create or open .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project) and paste the copied JSON. Open Settings → Tools & MCP and confirm the agentmesh server shows as connected.

Antigravity​

Open ~/.gemini/config/mcp_config.json (or .agents/mcp_config.json to scope it to one workspace) and paste the copied JSON. In the agent panel, open MCP Servers → Manage MCP Servers and confirm agentmesh is connected.

3. Browse what's available​

The Reference tab lists the MCP tools exposed by this AgentMesh deployment, grouped by category (Workspace, Artifacts, Workflow operations) and marked Read-only or Read-write. The page is generated from the server's current MCP tool catalogue.

4. Execute a workflow safely​

The MCP execution flow is intentionally explicit:

  1. Call agentmesh_workflows_execution_contract_get for the workflow. It reports required inputs, whether any assigned profile needs a repository, available repository roles, and attachment requirements.
  2. If you need files, call agentmesh_attachments_upload_create, upload the bytes with HTTP PUT to the returned 15-minute URL, then call agentmesh_attachments_upload_complete. Completion verifies the declared size and SHA-256 checksum and marks the attachment READY.
  3. Call agentmesh_workflows_execute with confirmed: true, a caller-generated idempotencyKey, the required goal, and any optional repository roles or ready attachment IDs.

Reusing the same idempotency key for the same project returns the existing workflow instance instead of creating a duplicate. Attachment metadata travels in the execution request; file bytes stay in object storage and are materialized on the worker before execution.

The current catalogue also provides read tools for organizations, projects, workflows, instances, runs, diagnostics and artifacts, plus governed write tools for cancellation, incident retry and approval decisions. Use the live Reference tab for exact input schemas.

Revoking a token​

Setup & Authentication tab → find the token under Active tokens → click revoke. It stops working immediately for every client using it; this can't be undone.