Skip to content

mcp.md

Latest commit

 

History

History
117 lines (78 loc) · 4.42 KB

mcp.md

File metadata and controls

117 lines (78 loc) · 4.42 KB
Raw

Connect AI agents with MCP

Artifact Server exposes one MCP endpoint at POST /mcp. MCP uses the same product operations and permissions as the CLI and HTTP API.

Connect a local client

Run the automatic connection command:

artifactserver connect

If more than one supported client is installed, select one client:

artifactserver connect codex
artifactserver connect claude
artifactserver connect cursor
artifactserver connect vscode

Inspect or remove a managed connection:

artifactserver doctor codex
artifactserver disconnect codex

The command registers a local stdio bridge. The bridge starts or locates the local service and handles its private credential.

The credential does not appear in client configuration, command output, or startup logs.

Connect to a team server

Add the exact MCP address to the client:

https://artifacts.example.com/mcp

The client opens the configured identity provider. Complete browser authorization, then return to the client.

The access token is valid for that exact /mcp resource. A token for another installation or application resource does not qualify.

Publish from an agent

MCP sends metadata and small results. Artifact files use the staged upload API.

An agent uses this sequence:

  1. Call artifact_capabilities to read limits and available features.
  2. Call artifact_create_upload with each path, size, media type, and SHA-256 fingerprint.
  3. Upload each file to its returned opaque upload URL.
  4. Call artifact_commit_upload with the publication target and idempotency key.

When the agent publishes a new version, it first reads the current version ID. It sends that ID as expectedCurrentVersionId.

Use the publication result

Every successful publication returns structured data and a short text summary.

{
  "links": {
    "review": "https://artifacts.example.com/review?...&view=focus",
    "artifact": "https://artifacts.example.com/artifacts/art_example",
    "version": "https://ver-example.content.example.com/"
  }
}

The server instructions tell the agent to share links.review first. This link opens the exact version full screen with comments.

links.artifact follows the current version. links.version opens the immutable raw artifact without the Artifact Server interface.

The agent must not place bootstrap URLs, access tokens, or credentials in chat.

Read operations use the same link roles. artifact_get.current.links.review opens the current exact version in full-screen Review. artifact_open.reviewUrl opens the selected exact version in Review, while artifact_open.browserUrl opens its raw immutable content. Agents should hand people the Review URL.

Tool groups

Group Tools
Discovery artifact_capabilities
Projects project_list, project_create, project_rename, project_archive, project_unarchive
Artifacts artifact_list, artifact_get, artifact_open, artifact_version_list, artifact_diff
Publication artifact_create_upload, artifact_commit_upload
Management artifact_set_visibility, artifact_set_tags, artifact_restore_version, artifact_delete
Comments comment_list, comment_get, comment_create, comment_reply, comment_update, comment_resolve, comment_delete
Git history planning project_git_history_status, project_git_history_estimate

Linked-artifact tools appear only when the deployment enables linked artifacts.

project_set_git_history enables one project only after an authorized caller confirms a fresh estimate. Provider configuration alone copies nothing. Agents should report the returned project state and must not describe waiting, degraded, or budget-limited history as ready.

Install the Artifact Server skill

Install the portable Agent Skill:

npx skills add plannotator/artifact-server

The skill routes artifact work and explicit server-administration work to separate internal instructions. It uses the CLI for files on the developer machine and MCP for server data and agent-held context.

In clients that expose installed skills as slash commands, publish finished work with a request such as:

/artifact-server upload that HTML design doc

The agent returns the full-screen review link first so the recipient can view and comment on the exact version.

Read the MCP product baseline for the protocol and authorization contracts.