# 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 a core agent surface for publishing text Artifacts, reading Agent Views, adding Revisions, and managing Share Links or Revision Links without shell access.

## Endpoint

Production MCP runs at `https://mcp.agent-paste.sh`. The transport endpoint is `POST /` using Streamable HTTP JSON-RPC. Protected Resource Metadata is at `/.well-known/oauth-protected-resource`; the root OAuth resource is `https://mcp.agent-paste.sh/`.

MCP does not accept API Keys or dashboard cookies. It verifies a WorkOS-issued OAuth bearer token and forwards authenticated calls to `api` and `upload` over service bindings.

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 MCP capabilities from the authenticated Workspace Member in `api`: `read`, `write`, and `share`.

| MCP scope | Backed by | Typical tools |
| --- | --- | --- |
| `read` | member `read` | `whoami`, `list_artifacts`, `read_artifact`, `list_revisions` |
| `write` | member `publish` | `publish_artifact`, `add_revision`, `delete_artifact`, `update_display_metadata` |
| `share` | member `admin` | `create_share_link`, `create_revision_link`, `list_access_links`, `revoke_access_link` |

## Tools

| Tool | Purpose |
| --- | --- |
| `whoami` | Return authenticated member, Workspace, and derived scopes. |
| `publish_artifact` | Publish a new text-only Artifact and return its Artifact URL. |
| `add_revision` | Add and publish a new text-only Revision and return its Artifact URL. |
| `list_artifacts` | List Artifacts in the Workspace. |
| `read_artifact` | Read latest Agent View for an Artifact. |
| `list_revisions` | List Revisions for an Artifact. |
| `delete_artifact` | Delete an Artifact. |
| `update_display_metadata` | Update an Artifact display title. |
| `create_share_link` | Create and mint a Share Link for the latest Revision. |
| `create_revision_link` | Create and mint a Revision 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. Binary uploads, multi-file folder uploads, standalone Bundle downloads, workspace settings, billing, and lockdown controls stay in CLI, REST, or dashboard surfaces.

`publish_artifact` and `add_revision` 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.