DevDock MCP User Guide

Welcome to DevDock's Model Context Protocol (MCP) integration. This guide explains how to use MCP to programmatically access and manage your reusable engineering context.

Table of Contents

1. What is MCP?
2. Getting Started
3. Authentication
4. Read Tools (Search & Retrieve)
5. Write Tools (Create & Manage)
6. Context Packs via MCP
7. Resources
8. Rate Limits
9. Common Workflows
10. Best Practices
11. Troubleshooting

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI agents interact with your DevDock workspace. Think of it as giving your AI agent access to persistent engineering context.

Instead of you manually copying snippets and explanations to the agent, the agent can search your context layer and retrieve exactly what it needs when it needs it.

What Your Agent Can Do

Once connected, your AI agent can:

• Search your workspace by keyword, type, or collection
• Retrieve full code snippets, notes, and documentation
• Read your saved configuration files
• Create new items and save context back to your workspace (if using read+write token)
• Find patterns you've documented and help you stay consistent

The User Experience

You don't interact with MCP directly. Instead, you just ask your agent naturally:

You: "Find React authentication examples in my DevDock workspace"

Your Agent (behind the scenes):
  1. Searches your vault for "React authentication"
  2. Finds your saved snippets
  3. Reads the full code and explanation
  4. Shows you the examples with context

That's it. Your agent handles the context retrieval automatically.

Why This Matters

• No copy-paste needed — agent retrieves context on demand
• Always up-to-date — agent uses your latest saved patterns
• Contextual help — agent can reference your actual code examples
• Operational memory — your workspace keeps reusable engineering context available

Getting Started

Step 1: Generate an MCP Token

1. Go to Settings → MCP Tokens
2. Click Generate Token
3. Choose a label (e.g., "Claude")
4. Select token scope:
   • Read — search and retrieve items (default, recommended for AI agents)
   • Read + Write — create, update, and delete items (only if your agent needs to save notes)
5. Copy the token immediately (shown only once)
6. Store it securely as an environment variable

Step 2: Connect Your AI Agent to DevDock

Simply paste this prompt into your AI agent to add DevDock as an MCP server:

Please add the DevDock MCP server to my MCP configuration. Use these details:

Name: devdock
Type: HTTP
URL: https://devdock.me/api/mcp
Authorization header: Bearer YOUR_DEVDOCK_MCP_TOKEN

Replace YOUR_DEVDOCK_MCP_TOKEN with the token you generated in Step 1.

That's it! Your agent will handle the configuration and make DevDock available immediately.

Works with Any MCP-Compatible Agent

This approach works with:

• Claude (Web, API, IDE extensions)
• Any MCP-compatible AI agent or assistant
• LLM-based tools that support the Model Context Protocol

Simply copy the prompt above and paste it into your agent. The agent will:

1. Parse the configuration details
2. Add DevDock to its available tools
3. Make your vault searchable in future conversations

Step 3: Start Using DevDock in Your Agent

Once connected, you can ask your agent to use DevDock:

Examples:

• "Search my DevDock vault for React hooks and show me examples"
• "Find any TypeScript snippets about authentication"
• "Look up Docker compose configurations and explain them"
• "What deployment guides do I have saved?"
• "Get me the API error handling pattern from my notes"

The agent will automatically:

1. Search your vault using search_devdock_items
2. Fetch full content with get_devdock_item or read_devdock_file
3. Use the knowledge to help with your task

No manual copying, no setup code needed — just ask your agent!

Authentication

Token Scopes

Every token has a scope that controls what operations it can perform:

Token Management

In Settings → MCP Tokens:

• View all active tokens with their creation date and last usage
• See the scope badge for each token (read or read+write)
• Revoke tokens at any time
• Set expiration dates (optional)
• Copy token prefixes for identification

Security Notes

• Tokens are shown only once at creation time — save them immediately
• Tokens are hashed at rest — DevDock never stores plaintext
• Each token is scoped to your account — no cross-user access possible
• Revoked or expired tokens are rejected at the auth layer
• Never commit tokens to version control — use environment variables instead

Read Tools (Search & Retrieve)

Read tools let your agent search and retrieve items from your vault. They work with read or read+write tokens.

search_devdock_items

Finds items across your vault by keyword, type, or collection. Your agent calls this first when looking for anything.

Ask your agent:

"Find React hook examples in my DevDock vault" "Search my DevDock for Docker commands, only show Commands" "What do I have saved about authentication in my Backend collection?"

get_devdock_item

Fetches the full content of a specific item by ID. Your agent uses this after searching to load the full snippet, note, or prompt.

Returns the full content, language, tags, collections, and all metadata. For File items, use read_devdock_file instead.

read_devdock_file

Reads the text content of a File item inline — no download needed.

Supported file types: txt, md, json, yaml, yml, xml, csv, toml

Binary files (PDF, images) return an error.

Ask your agent:

"Read the docker-compose file I saved in DevDock and explain it" "Show me the contents of my tsconfig file from DevDock"

list_devdock_collections

Lists all collections in your vault with item counts. Your agent uses this to orient itself before searching.

No parameters.

Ask your agent:

"What collections do I have in my DevDock vault?" "List my DevDock collections so I know where to look"

Write Tools (Create & Manage)

Write tools let your agent create, update, and delete items and collections. Requires a read+write token. If your agent has a read-only token it will tell you and ask you to generate a read+write token in Settings → MCP Tokens.

create_devdock_item

Creates a new item in your vault. Supported types: Snippet, Prompt, Note, Command, URL. File and Image items must be uploaded via the platform UI.

Ask your agent:

"Save this debounce function as a TypeScript snippet in my DevDock vault" "Add a new note to my DevDock about the auth architecture we just discussed" "Save this as a Prompt item in my AI Tools collection"

update_devdock_item

Updates fields on an existing item. Only provided fields are changed.

Providing tags replaces all existing tags — not just adds to them. For normal tag edits, use update_devdock_item_tags.

Ask your agent:

"Pin the API error handling note in my DevDock"

update_devdock_item_tags

Adds or removes tags on an existing item while preserving unrelated tags. This is the safest tool for requests like "add the performance tag."

At least one of add or remove must include a tag. The result returns the final tag list.

Ask your agent:

"Add the 'performance' tag to my debounce snippet in DevDock" "Remove the 'draft' tag from the API error handling note"

update_devdock_file

Overwrites the text content of a File item. Supported types: txt, md, json, yaml, yml, xml, csv, toml.

Ask your agent:

"Update my docker-compose file in DevDock with this new version"

create_devdock_collection

Creates a new collection. Optionally mark it as a Context Pack at creation time (see Context Packs via MCP). Free plan: maximum 3 collections.

Ask your agent:

"Create a new collection called 'DevOps' in my DevDock" "Pack my Next.js project as a starter boilerplate" ← triggers the full Context Pack flow

update_devdock_collection

Updates an existing collection. Can also promote or demote it as a Context Pack.

Setting isPack: false automatically clears all pack metadata.

Ask your agent:

"Make my 'NestJS' collection a public Context Pack" "Rename my Backend collection to 'API Patterns'"

delete_devdock_item

Moves an item to Trash. Restorable from the platform UI within 30 days.

Ask your agent:

"Delete the old auth snippet from my DevDock vault"

delete_devdock_collection

Moves a collection to Trash. Items inside are not deleted — they become uncategorized. Restorable within 30 days.

Ask your agent:

"Delete the 'Old Projects' collection from my DevDock"

Context Packs via MCP

A Context Pack is a collection promoted to a curated, shareable bundle — all items inside are delivered together in a single get_context_pack call. You can create or promote one entirely through your AI agent.

Scenario 1 — Promote an existing collection

You already have a collection and want to publish it as a Context Pack.

Just ask your agent:

"Make my 'NestJS' collection a public Context Pack"

The agent will ask you a few questions:

• Should it be public (discoverable by other users) or private?
• What's a short description for the discovery page?
• What are the main tech stack tags? (e.g. nestjs, typescript, postgres)

Then it presents the plan and waits for your confirmation before calling update_devdock_collection with isPack: true.

Scenario 2 — No collection yet: create a pack from scratch

You have a project or stack in mind and want to capture it as a reusable Context Pack.

Just ask your agent:

"Pack this project as a Next.js starter boilerplate"

The agent will not create anything immediately. Instead it works through a structured discovery flow:

Step 1 — Discovery questions The agent asks about your stack and intent:

• What is the tech stack? (e.g. Next.js + TypeScript + Tailwind + Prisma)
• What's the use case? (SaaS starter, internal tool, landing page, etc.)
• Should it be public or private?
• Any specific patterns, commands, or AI prompts you want captured?

Step 2 — Plan presentation Based on your answers, the agent reasons about what to create and presents the full plan before touching anything:

Here's what I'll create in your DevDock vault:

📦 Collection: next-saas-starter (Context Pack, public)
Stack tags: nextjs, typescript, tailwind, prisma, supabase

Items:
  • Snippet: App Router layout with auth guard — TypeScript
  • Snippet: Prisma client singleton — TypeScript
  • Snippet: Server action with error handling — TypeScript
  • Command: Initial project setup — bash
  • Command: Deploy to Vercel — bash
  • Prompt: Code review for this stack — AI prompt
  • Note: Architecture decisions and conventions

Ready to create this? (yes / adjust)

Step 3 — Execution (only after you confirm) The agent creates everything in order:

1. create_devdock_collection with isPack: true and all pack metadata
2. create_devdock_item for each item, all linked to the new collection

To-do after creation

Once the pack is live you can:

• Use get_context_pack to load it into any agent conversation
• Add more items by asking your agent: "Add a command to my next-saas-starter pack"
• Toggle visibility by asking: "Make my NestJS Context Pack private"

Resources

Resources follow the MCP resource protocol and can be read directly by clients that support it.

Resource: devdock://item/{id}

Returns the same payload as get_devdock_item (file URLs are omitted).

Example:

devdock://item/cmo8grfgk0000enp9jviwxkyr

Clients supporting resources can enumerate all items in your vault using this resource pattern.

Resource: devdock://collections

Returns the same payload as list_devdock_collections with all collections and item counts.

Rate Limits

All limits use a sliding 1-hour window per user.

What counts as "write":

• create_devdock_item
• update_devdock_item
• update_devdock_item_tags
• update_devdock_file
• create_devdock_collection
• update_devdock_collection
• delete_devdock_item
• delete_devdock_collection

Hitting the Limit

If you exceed the rate limit, you'll get an error:

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32603,
    "message": "Rate limit exceeded. Retry in 120s"
  }
}

How to stay within limits:

• Ask your agent to be specific ("react hooks" not just "react") — precise searches use fewer calls
• For bulk operations spread them across multiple conversations or upgrade to Pro

Common Workflows

Workflow 1: Agent Answering Questions with Your Knowledge

Your agent searches your vault and uses the knowledge to answer questions.

You ask the agent:

"I need to implement React error boundaries. Do I have any examples in my vault?"

Behind the scenes, the agent:

1. Calls search_devdock_items with query "React error boundaries"
2. Gets back item IDs from your vault
3. Calls get_devdock_item to fetch the full code example
4. Uses that knowledge to explain and help you

You get:

Based on your saved snippet, here's how to implement error boundaries:

[Shows your exact code example with explanation]

This pattern catches errors in child components and displays a fallback UI.

No setup needed — just ask your agent!

Workflow 2: Agent Explaining Your Configuration Files

Your agent reads a configuration file from your vault and explains it.

You ask:

"Explain the docker-compose file I saved in DevDock"

The agent:

1. Searches for "docker-compose" in your vault
2. Finds the File item
3. Reads it with read_devdock_file
4. Explains the setup, services, and configuration

This is useful when you need context on how your deployment or infrastructure is set up.

Workflow 3: Agent Finding the Right Pattern

You're building a feature and need to follow your own best practices.

You ask:

"Search my DevDock for TypeScript API patterns and show me the error handling approach I've documented"

The agent:

1. Searches your vault for relevant items
2. Retrieves your documented patterns
3. Shows you the exact approach you've saved
4. Helps you implement it consistently

Keeps your code aligned with your own standards.

Workflow 4: Agent Taking Notes (with read+write token)

If your agent has a read+write token, it can save knowledge back to your vault.

You ask:

"I just explained REST API best practices. Save that as a note in my DevDock vault for future reference"

The agent:

1. Takes what was discussed
2. Creates a new Note item with create_devdock_item
3. Tags it appropriately
4. Saves it to your vault

Now that knowledge is preserved for future sessions!

Best Practices

1. Use Descriptive Titles

Good:

• "useCallback Hook for Memoized Callbacks"
• "Postgres Connection Pooling with PgBouncer"
• "API Error Handling Middleware"

Bad:

• "stuff"
• "important"
• "code"

Descriptive titles help with search and give context to agents.

2. Tag Consistently

Create a tagging convention and stick to it:

• Use lowercase: react, not React
• Use singular where possible: hook, not hooks
• Be specific: useEffect, not just react
• Include technology: typescript, nodejs, postgres

Example tags for a snippet:

{
  "tags": ["typescript", "react", "hooks", "memoization"]
}

3. Group Related Items in Collections

Create collections by domain or project:

• Frontend: React components, styling patterns, hooks
• Backend: API endpoints, database queries, auth
• DevOps: Docker, CI/CD, deployment
• Tools: CLI commands, scripts, utilities

This makes searching much faster and more focused.

4. Use the Right Item Type

5. Keep Content Focused

• One concept per item (don't mix React and Docker in one snippet)
• Trim unnecessary code or comments
• Link to related items in descriptions

6. Rotate Tokens Regularly

• Generate a separate token for each agent or tool
• Revoke tokens you no longer use in Settings → MCP Tokens
• Use read-only tokens for agents that only need to look things up
• Use read+write tokens only for agents you explicitly trust to save and edit

Troubleshooting

"Invalid token" or "Unauthorized"

• Check that the token is correctly formatted in the Authorization header: Bearer YOUR_TOKEN
• Verify the token hasn't been revoked in Settings → MCP Tokens
• Check if the token has expired
• Regenerate a new token if needed

"Rate limit exceeded"

• Wait for the number of seconds specified in the error message
• Consider caching results locally
• Batch multiple operations into fewer API calls
• Upgrade to Pro for higher limits

"This token has read-only scope"

• You're trying to use a write tool with a read-only token
• Generate a new read+write token in Settings → MCP Tokens
• Store it securely and use it for write operations

Search returns no results

• Try more general keywords (e.g., "react" instead of "useEffect advanced patterns")
• Check that items are tagged properly
• Use list_devdock_collections to see what collections exist
• Verify items are in the collection you're filtering by

File upload or update fails

• Check that the file type is supported (txt, md, json, yaml, yml, xml, csv, toml)
• Verify the content doesn't exceed 100,000 characters
• Binary files (PDF, images) are not supported

Add or remove tags without losing existing tags

Use update_devdock_item_tags for normal tag edits. It preserves unrelated tags and returns the final tag list:

{
  "id": "item-id",
  "add": ["new-tag"],
  "remove": ["draft"]
}

Only use the tags field on update_devdock_item when you intentionally want to replace the entire tag set.

Next Steps

1. Generate your first token → Go to Settings → MCP Tokens and create a Read token
2. Test with your agent → Ask your AI agent to search your DevDock vault
3. Build your vault → Add more items, organize them into collections, use tags
4. Expand to read+write (optional) → Generate a read+write token if you want your agent to save notes back to your vault
5. Customize your workflow → Use DevDock as the knowledge source for your agent-powered tasks

Start small: Create one collection, add 5-10 items, and ask your agent to find them. You'll quickly see the power of having AI access to your knowledge!

Need help? Check the main MCP documentation for technical specifications and advanced configuration.