# MCP Server

Hosted agents without CLI access can publish, inspect, revise, and share text Artifacts over OAuth-only MCP.

Human page: /docs/mcp
Markdown page: /docs/mcp.md

## When to use MCP

Use MCP when an agent runs inside a hosted tool that can connect to remote MCP servers but cannot install npm packages, spawn a CLI, or use a local keychain.

MCP is not a weaker side channel. It is the hosted-agent surface for publishing text Artifacts, reading Agent Views, adding Revisions, and explicitly managing Share Links and snapshot links without shell access.

## Endpoint

Production MCP runs at `https://mcp.agent-paste.sh`. Opening `GET /` returns endpoint metadata for humans and agents. Protocol calls use `POST /` with Streamable HTTP JSON-RPC and an OAuth bearer token. Protected Resource Metadata is at `/.well-known/oauth-protected-resource`; the root OAuth resource is `https://mcp.agent-paste.sh/`.

MCP verifies a WorkOS-issued OAuth bearer token and forwards authenticated calls to `api` and `upload` over service bindings. Dashboard cookies and local CLI credentials do not authenticate MCP calls.

Connect `https://mcp.agent-paste.sh` in the host, complete OAuth, then run `whoami` first. The WorkOS user must already belong to a Workspace, which dashboard sign-in or `agent-paste login` creates.

## Capability scopes

WorkOS AuthKit tokens carry standard OAuth scopes. agent-paste derives capabilities from the authenticated Workspace Member in `api`, using one shared scope vocabulary: `read` and `publish` (`admin` is dashboard-only and no MCP tool needs it).

| Scope | Grants | Tools |
| --- | --- | --- |
| `read` | View your own Artifacts and links | `whoami`, `list_artifacts`, `read_artifact`, `read_file`, `list_revisions`, `list_access_links` |
| `publish` | Change your own content and manage visibility/access links | `publish_artifact`, `add_revision`, `multi_edit`, `delete_artifact`, `update_display_metadata`, `set_visibility`, `create_revision_link`, `revoke_access_link` |

## Tools

| Tool | Purpose |
| --- | --- |
| `whoami` | Return authenticated member, Workspace, and derived scopes. |
| `publish_artifact` | Publish a NEW text-only Artifact (new private_url). Content-only and private. To change published work, use add_revision instead. |
| `add_revision` | Revise an EXISTING Artifact: pass its artifact_id to publish a new Revision. Same stable private_url; live-updates open viewers. Use this to change published work, not publish_artifact. |
| `multi_edit` | Edit one stored file with literal find/replace, then publish the result as a new Revision under the same Artifact. |
| `list_artifacts` | List Artifacts in the Workspace. |
| `read_artifact` | Read latest Agent View for an Artifact. |
| `read_file` | Read one stored file's plaintext body or metadata so an agent can edit against the current bytes. |
| `list_revisions` | List Revisions for an Artifact. |
| `delete_artifact` | Delete an Artifact. |
| `update_display_metadata` | Update an Artifact display title. |
| `set_visibility` | Set visibility. `private` revokes active Access Links; `unlisted` returns `unlisted_url`. |
| `create_revision_link` | Create and mint a snapshot Access Link for a specific Revision. |
| `list_access_links` | List Share Links and Revision Links for an Artifact. |
| `revoke_access_link` | Revoke a Share Link or Revision Link. |

## Limits

The MCP publish tools are text-only. Use the CLI for binary uploads and multi-file folder uploads. Ready Bundle URLs are exposed through Agent View/read tools. Workspace settings, billing, and lockdown controls stay in the dashboard.

`publish_artifact`, `add_revision`, and `multi_edit` are content-only and private: they take no visibility input and return a single `private_url` (the login-walled `/v/<artifactId>` clean viewer for the Workspace Member), with no `shared` field. To make an Artifact reachable without login, call `set_visibility` with `visibility: "unlisted"`; it mints or reuses the one Share Link that follows the latest Revision and returns `unlisted_url`. To remove no-login access, call `set_visibility` with `visibility: "private"`. To change a published Artifact, call `add_revision` or `multi_edit` with its `artifact_id` rather than `publish_artifact`: the `private_url` is stable and already-open viewers live-update to the new Revision, whereas a second `publish_artifact` mints a separate Artifact on a new link. Artifact IDs, Revision IDs, and content URLs are available through the read/list/link tools. The tools also accept optional idempotency keys; when omitted, the server derives stable keys from the OAuth subject, JSON-RPC id, and tool name.

Artifact lifetime follows Workspace Auto Deletion policy. MCP callers do not choose TTL.