PasteAI is an MCP server that lets you publish, manage, and retrieve markdown documents via AI editor integration, a REST API, and a clean web UI.
Publish documents – Create a new markdown document with a title, content, optional author, and visibility (public or unlisted). Get back a shareable URL.
List documents – Retrieve a list of recently published public documents.
Get a document – Fetch a specific document by its ID, including full markdown content or raw markdown source via /d/{id}/raw.
Update a document – Modify the title or content of an existing document.
Delete a document – Permanently remove a document by its ID.
Search documents – Search by keyword within document titles.
Set visibility – Change a document's visibility to public, unlisted (link-only), or private.
Web UI – Browse and read documents in a themed interface (Light, Dark, Arctic, Catppuccin, etc.).
MCP integration – Works with Claude Code, Kiro, opencode, and claude.ai as a Custom Connector via streamable HTTP, with support for embedded, local, and remote modes and API key auth.
Flexible deployment – Run persistently with Docker Compose, or access privately via Tailscale.
Human review of beautiful reports, generated by AI
AI publishes markdown documents via MCP. You read them in a clean, themed web UI.
Run /setup in Claude Code — it installs the binary and configures MCP. Then restart your editor to activate.
Or install manually:
# macOS
brew install pasteai/pasteai/pasteai
# Windows
scoop bucket add pasteai https://github.com/pasteai/scoop-pasteai
scoop install pasteai
# Linux (Debian/Ubuntu)
# Download the .deb from https://github.com/pasteai/pasteai/releases/latest
# Any platform — prebuilt binary
curl -sSL https://raw.githubusercontent.com/pasteai/pasteai/main/install.sh | sh
# With Go
go install github.com/pasteai/pasteai/cmd/pasteai@latestThen run pasteai setup to register with your AI editor(s). It configures Claude Code, Kiro, and opencode simultaneously.
To configure manually, add the entry to the appropriate config file:
Claude Code (~/.claude.json) and Kiro (~/.kiro/settings/mcp.json):
{
"mcpServers": {
"pasteai": {
"command": "/full/path/to/pasteai",
"args": ["mcp"]
}
}
}opencode (~/.config/opencode/opencode.json):
{
"mcp": {
"pasteai": {
"type": "local",
"command": ["/full/path/to/pasteai", "mcp"]
}
}
}Use the absolute path from which pasteai or $(go env GOPATH)/bin/pasteai — AI editors do not inherit your shell PATH.
Restart your editor, then ask: "Summarise what we discussed and publish it."
Related MCP server: doc-ingestor-mcp
Command | Description |
| Configure MCP in Claude Code, Kiro, and opencode (interactive or via flags) |
| Configure without prompts (non-interactive) |
| Diagnose common setup problems |
| Start the HTTP server |
| Start the MCP server (used by Claude Code) |
| Print version |
Situation | Mode |
Claude Code on your laptop | Embedded — default, nothing to configure |
Claude running in a container or remote VM | Local server — run |
Sharing with a team or reading across devices | Remote — deploy with |
Add the MCP config above and restart Claude Code. When Claude first calls a tool, PasteAI starts a local server automatically. Documents stored at ~/.pasteai/documents.db and as plain markdown files at ~/.pasteai/documents/{id}.md — readable without the server running.
Run the server persistently with Docker Compose and point the MCP client at it:
# docker-compose.yml
services:
pasteai:
image: ghcr.io/pasteai/pasteai:latest
ports:
- "8080:8080"
volumes:
- ${HOME}/.pasteai:/data
restart: unless-stoppedmkdir -p ~/.pasteai
docker compose up -dIn ~/.claude.json:
{
"mcpServers": {
"pasteai": {
"command": "/full/path/to/pasteai",
"args": ["mcp"],
"env": { "PASTEAI_URL": "http://localhost:8080" }
}
}
}Good when you want the server always running, independent of Claude Code. For systemd, launchd, or nohup alternatives, see docs/server-setup.md.
Point PASTEAI_URL at any PasteAI instance. Both PASTEAI_API_KEY and -base-url are required on the server for remote access to work correctly.
Start the server with:
pasteai serve -api-key <your-key> -base-url https://your-server.example.comIn ~/.claude.json:
{
"mcpServers": {
"pasteai": {
"command": "/full/path/to/pasteai",
"args": ["mcp"],
"env": {
"PASTEAI_URL": "https://your-server.example.com",
"PASTEAI_API_KEY": "your-key"
}
}
}
}To read documents from your phone or another machine, use Tailscale. Start pasteai serve, then browse to http://<tailscale-ip>:8080 from any device on your tailnet. Set -base-url http://<tailscale-ip>:8080 so document links resolve correctly.
publish_document — publish a markdown document, returns a shareable URL.
Parameter | Required | Description |
| yes | Document title |
| yes | Markdown content |
| no | Author name |
| no |
|
list_documents — returns recent public documents.
get_document — retrieve a document by ID, including its full markdown content.
Parameter | Required | Description |
| yes | Document ID |
update_document — update the title or content of an existing document.
Parameter | Required | Description |
| yes | Document ID |
| no | New title (omit to keep existing) |
| no | New markdown content (omit to keep existing) |
delete_document — permanently delete a document by ID.
Parameter | Required | Description |
| yes | Document ID |
To connect a deployed PasteAI server to claude.ai as a Custom Connector, start the server with -enable-mcp-http. This mounts a stateless streamable-HTTP MCP endpoint at /mcp alongside the web UI:
pasteai serve \
-api-key <your-key> \
-base-url https://your-server.example.com \
-enable-mcp-httpThen in claude.ai → Settings → Connectors, add:
https://your-server.example.com/mcpThe /mcp endpoint requires the same Bearer token as the API when -api-key is set. The stdio transport (pasteai mcp) is unaffected — both can run simultaneously.
Method | Path | Description |
|
| Create a document |
|
| List recent public documents |
|
| Get a document (with content) |
|
| Update title or content |
|
| Delete a document |
|
| Raw markdown source |
curl -X POST http://localhost:8080/api/documents \
-H 'Content-Type: application/json' \
-d '{"title": "My Report", "content": "# Hello\n\nThis is my report.", "author": "Claude"}'Response includes a url field: http://localhost:8080/d/{id}
Switch themes using the selector in the top nav. Choice is saved in localStorage.
Light · Dark · Emerald · Arctic · Catppuccin Mocha · Catppuccin Latte · Catppuccin Frappé
Permanently delete a PasteAI document by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The document ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds 'Permanently', reinforcing irreversibility, but does not provide additional context beyond annotations, such as auth requirements or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence with no unnecessary words. Front-loaded with the action and resource, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description covers the core functionality. It could mention return values or error handling, but it is adequate for the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter 'id' described as 'The document ID to delete'. The description adds 'by ID' but no additional meaning beyond the schema, so baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently delete a PasteAI document by ID', which is a specific verb and resource. It distinguishes from sibling tools like get_document or update_document by emphasizing permanence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives or when not to use it. It is implied that you use it for permanent deletion, but no exclusions or comparisons are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a PasteAI document by ID, including its full markdown content
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The document ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint true and readOnlyHint false, which contradicts the description's 'Retrieve' action. The description does not disclose any behavioral traits beyond retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, succinct sentence that conveys the essential information without any extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the purpose and output for a simple retrieval tool, though it could optionally mention additional returned fields like metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the single parameter 'id' is already explained. The description adds context about returning markdown content but does not enhance parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve a PasteAI document by ID') and specifies the return content ('full markdown content'). It distinguishes from sibling tools like delete_document and list_documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives such as search_documents. Sibling tools are listed but no comparison is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent documents published to PasteAI
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description calls this a list operation, implying read-only behavior, but annotations set readOnlyHint to false and destructiveHint to true, creating a contradiction. The description fails to clarify this inconsistency or add any behavioral context beyond the contradictory annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, efficiently conveying the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple with no parameters, the description lacks details about what 'recent' means, any pagination, or the return format. Given no output schema, this is a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so schema coverage is 100%. By baseline rules, a score of 4 is appropriate since no additional parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List recent documents published to PasteAI', providing a specific verb and resource. However, it does not differentiate from sibling tools like search_documents or get_document, earning a 4 instead of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives (e.g., search_documents for filtering). There is no mention of when-not-to-use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List human reviews (comments) on a PasteAI document. Use this to read feedback before revising with update_document.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The document ID | |
| include_resolved | No | Include resolved comments in the response (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'List', implying a read-only operation, but annotations set readOnlyHint: false and destructiveHint: true, suggesting possible write or destructive side effects. The description does not address this discrepancy nor explain behavioral traits like the openWorldHint. It adds minimal behavioral context beyond the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences, 14 words) and front-loads the core purpose. Every word adds value, with no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and usage but lacks information about the return format (no output schema) and does not address potential side effects hinted by annotations. For a simple tool with two parameters, it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description does not add extra meaning beyond the schema, so it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('list') and resource ('human reviews/comments') and specifies the context ('on a PasteAI document'). It distinguishes the tool from siblings by focusing on a specific sub-resource (reviews) not covered by other tools like get_document or list_documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use this to read feedback before revising with update_document.' It does not specify when not to use the tool or list alternatives, but the intended workflow is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a markdown document to PasteAI and get back a shareable URL
| Name | Required | Description | Default |
|---|---|---|---|
| author | No | Optional author name (e.g. the AI model name) | |
| content | Yes | The document content in markdown format. Mermaid diagram blocks (```mermaid) are rendered as diagrams. | |
| title | Yes | The title of the document | |
| visibility | No | Visibility: public (default, appears in listings) or unlisted (link-only, not listed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, but description does not explain what destructive behavior occurs (e.g., overwriting a previous publish). No mention of authentication, rate limits, or state prerequisites. Description adds little beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with 12 words, no wasted verbiage. Front-loaded with verb and outcome. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, 8 siblings, and no output schema, the description is too brief. It does not clarify the relationship to set_visibility or update_document, nor does it explain the destructive nature or the return format beyond 'shareable URL'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters are fully described in the input schema (100% coverage). The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'publish', the resource 'markdown document', and the outcome 'get back a shareable URL'. This distinguishes it from siblings like update_document or delete_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., set_visibility, update_document). The description does not mention prerequisites, when not to use, or comparisons with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search PasteAI documents by title keyword
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Keyword to search for in document titles |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims the tool performs a search operation, which is typically non-destructive, yet the annotations set destructiveHint to true, contradicting the described behavior. No additional behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no superfluous information, efficiently conveying the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fails to indicate what the tool returns (e.g., list of documents, metadata). For a search tool, this is a notable omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter 'query' already described as a keyword search. The description adds no further meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'search', the resource 'PasteAI documents', and the scope 'by title keyword', distinguishing it from siblings like 'list_documents' which likely returns all documents without filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching documents by title, but it does not explicitly state when not to use this tool or suggest alternatives for other search criteria (e.g., content search).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the visibility of an existing PasteAI document
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The document ID | |
| visibility | Yes | New visibility: public, unlisted, or private |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows it is a mutation. The description adds no further behavioral context beyond confirming it changes visibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, concise sentence with no waste. It is front-loaded and efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter mutation tool with schema covering all parameters, the description is mostly complete. It lacks usage context but combined with schema and annotations, it provides sufficient information for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with clear descriptions. The description does not add any additional meaning beyond what the schema already provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'change' and the resource 'visibility of an existing PasteAI document'. It is specific to visibility, distinguishing it from siblings like update_document which may change other fields, and publish_document which implies setting to public.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for changing visibility but does not explicitly state when to use this tool versus alternatives like update_document or publish_document. No when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the title or content of an existing PasteAI document. Provide at least one of title or content.
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | New markdown content (omit to keep existing) | |
| id | Yes | The document ID to update | |
| title | No | New title (omit to keep existing) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so description's 'update' is consistent and adds no new behavioral traits. It does not discuss side effects or reversibility. Adequate but not enhanced beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and constraint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential behavior for a simple update tool. Could optionally mention return value, but not necessary given no output schema. The 'at least one' constraint is well-stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all parameters 100%, so baseline is 3. Description adds a usage constraint (at least one of title or content) but doesn't deepen meaning of individual parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing document by title or content, and explicitly requires at least one of these fields. This distinguishes it from sibling tools like delete_document, get_document, list_documents, publish_document, search_documents, and set_visibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit constraint 'provide at least one of title or content', guiding correct usage. It does not explicitly mention when not to use, but the sibling list allows the agent to infer alternatives. Minor improvement could add exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.0.19list_reviewspublish_document1 field changedInput schema / properties / content / descriptionPrevious value: -"The document content in markdown format"New value: +"The document content in markdown format. Mermaid diagram blocks (```mermaid) are rendered as diagrams."v0.0.14delete_documentget_documentlist_documentspublish_documentsearch_documentsset_visibilityupdate_documentv0.0.9get_documentlist_documentspublish_documentupdate_documentv0.0.6get_documentupdate_documentv0.0.3list_documentspublish_documentScored across 8 tools
Each tool targets a distinct operation: create (publish), read (get, list, search), update, delete, visibility, and reviews. No two tools overlap in purpose, and descriptions reinforce their unique roles.
All tools follow a consistent verb_noun snake_case pattern, with verbs like delete, get, list, publish, search, set, and update. Minor singular/plural variations are conventional and not confusing.
Eight tools cover the full document lifecycle without unnecessary redundancy. This is a well-scoped set for a PasteAI document management server.
The server covers create, read, update, delete, visibility control, search, and reviews. There are no obvious dead ends, and the workflow of reading reviews before updating is explicitly supported.
Publish and share access-controlled Markdown documents from any MCP-enabled AI tool.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Publish AI-generated HTML & Markdown to a hosted, shareable URL via MCP.
