Skip to main content
The Craft MCP server provides 32+ tools for working with Craft documents, blocks, collections, search, and tasks.

​
Overview

The Craft MCP Server is a remote MCP server hosted at https://agents.craft.do/docs/mcp that exposes your Craft workspace through the Model Context Protocol. It provides comprehensive access to documents, blocks, collections, search, and task management.

​
Key Features

32+ Tools

Comprehensive API covering all Craft features

OAuth 2.0

Secure authentication with your Craft account

Real-time Access

Direct access to your live Craft workspace

Document Search

Full-text search across all your documents

​
Setup

1

Tell the agent

Simply say: “Add Craft as a source”
2

OAuth flow

The agent will create the source and trigger OAuth authentication
3

Authorize

Authorize Craft Agents to access your workspace in the browser
4

Start using

Once connected, the agent can access your Craft documents
The agent will automatically configure the source with the correct MCP URL and OAuth settings.

​
Source Configuration

Here’s what the Craft MCP source configuration looks like:
config.json
{
  "id": "craft_a1b2c3d4",
  "name": "Craft",
  "slug": "craft",
  "provider": "craft",
  "type": "mcp",
  "icon": "https://cdn.craft.do/assets/craft-logo.png",
  "tagline": "Document editor, notes, and knowledge base",
  "mcp": {
    "transport": "http",
    "url": "https://agents.craft.do/docs/mcp"
  },
  "authType": "oauth",
  "oauth": {
    "authorizationUrl": "https://api.craft.do/oauth/authorize",
    "tokenUrl": "https://api.craft.do/oauth/token",
    "clientId": "craft-agents",
    "scope": "documents:read documents:write blocks:read blocks:write"
  }
}

​
Available Tools

The Craft MCP server exposes the following tool categories:

​
Document Management

mcp__craft__listDocuments({
  spaceId?: string,
  folderId?: string,
  limit?: number
})

​
Block Operations

Craft documents are composed of blocks. Each block represents a piece of content: 
mcp__craft__listBlocks({
  documentId: string
})

​
Collections

Collections are groups of related documents: 
mcp__craft__listCollections({
  spaceId?: string
})
Full-text search across your Craft workspace:
Search Documents
mcp__craft__searchDocuments({
  query: string,
  spaceId?: string,
  limit?: number
})
Search supports natural language queries and returns ranked results based on relevance.

​
Task Management

Manage tasks within Craft documents: 
mcp__craft__listTasks({
  documentId?: string,
  status?: 'pending' | 'completed',
  assignee?: string
})

​
Usage Examples

Here are some common workflows with the Craft MCP server:

​
Creating a New Document

"Create a new document in Craft called 'Meeting Notes' with a section for attendees and agenda"
The agent will:
  1. Call mcp__craft__createDocument to create the document
  2. Call mcp__craft__createBlock to add blocks for attendees and agenda
  3. Return the document ID and URL

​
Searching Documents

"Search my Craft documents for anything related to the Q4 roadmap"
The agent will:
  1. Call mcp__craft__searchDocuments with query “Q4 roadmap”
  2. Return ranked results with document titles and snippets
  3. Offer to open specific documents for more details

​
Managing Tasks

"Show me all pending tasks in my Craft workspace"
The agent will:
  1. Call mcp__craft__listTasks with status “pending”
  2. Display tasks grouped by document or due date
  3. Offer to mark tasks as complete or update them

​
Organizing with Collections

"Create a collection for all project-related documents and add the last 5 documents I created"
The agent will:
  1. Call mcp__craft__createCollection with name “Projects”
  2. Call mcp__craft__listDocuments to find recent documents
  3. Call mcp__craft__addToCollection for each relevant document

​
Permissions

Craft MCP tools are automatically configured for Explore mode safety: Allowed in Explore mode:
  • All list*, get*, search* operations (read-only)
  • Viewing documents, blocks, collections, and tasks
Requires Ask to Edit or Auto mode:
  • create*, update*, delete* operations
  • Modifying documents, blocks, or collections
  • Creating or completing tasks
See the permissions.json configuration in the Craft source for details.

​
Rate Limits

The Craft MCP server has the following rate limits:
  • 100 requests per minute per workspace
  • 1000 requests per hour per workspace
  • 10,000 requests per day per workspace
If you exceed rate limits, the server will return 429 Too Many Requests. The agent will automatically back off and retry.

​
Troubleshooting

​
Connection Failed

MCP connection failed: Server unreachable
Solutions:
  1. Check your internet connection
  2. Verify the MCP URL is correct: https://agents.craft.do/docs/mcp
  3. Try reconnecting the source

​
Authentication Expired

Authentication expired or was revoked
Solutions:
  1. Re-authenticate by triggering OAuth flow again
  2. Ask the agent: “Reconnect to Craft”
  3. Check that your Craft account is active

​
No Documents Found

No documents found in workspace
Possible causes:
  1. Your workspace is empty
  2. OAuth scope doesn’t include document access
  3. Documents are in a space you don’t have access to

​
Best Practices

1

Use specific queries

When searching, use specific keywords for better results
2

Batch operations

When creating multiple documents or blocks, batch operations for efficiency
3

Handle errors gracefully

Check for rate limits and authentication errors in workflows
4

Cache document IDs

Store frequently accessed document IDs to reduce lookups

​
Next Steps

MCP Overview

Learn more about the Model Context Protocol

Custom MCP Servers

Add other MCP servers to extend functionality

Build docs developers (and LLMs) love

Get started for freeTalk to us