Haiven MCP Server

Connect your AI tools directly to your organization's Haiven prompts. Use expertly crafted prompts from Claude Desktop, VS Code, Cursor, and other AI tools without switching apps.

What You Get

• ✅ Access your organization's expert prompts directly in your AI tools
• ✅ Ready-to-use prompts for user stories, code reviews, architecture decisions, PRDs, and more
• ✅ No app switching - stay in your current workflow
• ✅ Works with any MCP-compatible tool - Claude Desktop, VS Code, Cursor, and more
• ✅ Seamless integration - prompts appear as if they're built into your AI tool
• ✅ Context preservation - your conversations continue uninterrupted
• ✅ Native MCP prompts - each Haiven prompt appears as a first-class MCP prompt
• ✅ Smart caching - faster performance with intelligent content caching
• ✅ Backward compatibility - existing tools still work alongside new prompt interface

Quick Start

Prerequisites: Docker installed on your machine

1. Get your API key from your Haiven web interface (API Keys → Generate New API Key)

   🔒 Security note: Store your API key securely and never commit it to version control

   For detailed steps: See Get Your API Key section below

2. Add this configuration to your AI tool's MCP settings:

   "haiven-prompts": {
     "command": "docker",
     "args": [
       "run", "-i", "--rm", "--pull=always",
       "-e", "HAIVEN_API_KEY=your-api-key-here",
       "-e", "HAIVEN_API_URL=https://your-haiven-server.com",
       "ghcr.io/tw-haiven/haiven-mcp-server:latest"
     ]
   }
   

   Where to add it:

   • Claude Desktop: ~/Library/Application Support/Claude/config.json (Mac) or %APPDATA%\Claude\config.json (Windows)
   • VS Code: Settings → Extensions → search "mcp" → Configure MCP servers
   • Cursor: ~/Library/Application Support/Cursor/config.json (Mac) or %APPDATA%\Cursor\config.json (Windows)

3. Replace the values:

   • your-api-key-here → Your API key from step 1
   • https://your-haiven-server.com → Your organization's Haiven server URL

4. Restart your AI tool

Test Your Setup

After completing the setup, verify everything works:

1. Check MCP connection: In your AI tool, look for "haiven-prompts" in the connected servers list
2. Test prompt access: Ask your AI tool: "What Haiven prompts are available?"
3. Verify response: You should see a list of prompts from your organization's Haiven system

✅ Success indicators:

• Your AI tool shows "haiven-prompts" as connected
• You can see your organization's prompts listed
• No authentication errors in the AI tool's logs

Basic Usage

After setup, you can access your Haiven prompts in two ways:

Native MCP Prompts (Recommended)

Each Haiven prompt appears as a first-class MCP prompt in your AI tool:

Direct prompt invocation:

"Use the ADR prompt to help me document this architecture decision"

Browse available prompts:

"Show me all available Haiven prompts"

Use prompts with context:

"Use the user story prompt to break down this feature request"

Legacy Tools (Backward Compatibility)

For clients that need the tool-based interface:

List all prompts:

"What Haiven prompts are available?"

Use a specific prompt:

"Use the Haiven prompt for creating user stories and help me break down this feature request"

Execute prompts with context:

"Execute the Haiven code review prompt on my current file"

Common Issues

🔧 Quick fixes for the most common problems:

• "Docker not found": Install Docker Desktop from docker.com and ensure it's running
• "Authentication failed": Double-check your API key and Haiven server URL are correct
• "MCP server not connecting": Restart your AI tool and verify the configuration file syntax

For more help: See Complete Troubleshooting Guide

Get Your API Key

1. Open Haiven in your browser (the web version your organization uses)
2. Login with your work credentials (OKTA/SSO)
3. Click "API Keys" in the top navigation menu
4. Click "Generate New API Key"
5. Fill out the form:
   • Name: "AI Tool Integration"
   • Expiration: 30 days (or your preference)
6. Copy the generated key - Save it immediately! You won't see it again
7. Store it safely (password manager recommended)

Detailed Documentation

• Complete Setup Guide - Step-by-step instructions for all AI tools
• Troubleshooting - Common issues and solutions
• Developer Guide - Local development and contributing

---

Technical Details & IT Information

Architecture

This MCP server provides a bridge between AI applications and the Haiven AI prompts API using the Model Context Protocol.

Key Features:

• Standard MCP Protocol: JSON-RPC 2.0 over stdin/stdout
• Native MCP Prompts: Each Haiven prompt appears as a first-class MCP prompt
• Smart Caching: Two-tier caching (metadata + content) for optimal performance
• API Key Authentication: Secure connection to your Haiven server
• Backward Compatibility: Legacy tools still work alongside new prompt interface
• Multi-Architecture Docker: Supports AMD64 and ARM64
• Security Hardened: Comprehensive security scanning and validation

Available Interfaces

Native MCP Prompts (Primary Interface)

Each Haiven prompt is registered as a native MCP prompt with:

• Direct invocation by prompt identifier (e.g., /adr-9e6a21eb)
• Rich metadata including title, description, and categories
• Smart caching for optimal performance
• Seamless integration with MCP-compatible AI tools

MCP Tools

get_prompts Retrieves all available prompts with their metadata from the cached prompt service.

Parameters: None

Returns: JSON object with prompts array and total count

Example Response:

{
  "prompts": [
    {
      "identifier": "adr-9e6a21eb",
      "title": "Architecture Decision Record",
      "categories": ["architecture"],
      "help_prompt_description": "Create structured ADRs",
      "help_user_input": "Describe the decision context",
      "help_sample_input": "We need to choose a database for our new service",
      "type": "chat"
    }
  ],
  "total_count": 1
}

get_prompt_text Fetches the content of a specific prompt by ID with full metadata.

Parameters:

• prompt_id (required): ID of the prompt to fetch

Returns: JSON object containing the prompt content

Example Response:

{
  "prompt_id": "prd-template-ideate",
  "title": "Draft PRD",
  "content": "You are a product manager. Help create a comprehensive Product Requirements Document...",
  "type": "chat",
  "follow_ups": ["What metrics should we track?", "How do we prioritize features?"]
}

get_casper_workflow Provides the Casper workflow methodology for AI development guidance, supporting both sharing with LLMs and saving to tool-specific directories.

Parameters:

• section (optional): "explore", "craft", "polish", or "full" (default)
• mode (optional): "share" (default) or "save"
• tool_context (optional, save mode): "cursor", "vscode", or "generic" (auto-detected)

Modes:

• Share: Returns Casper workflow content for immediate use by the LLM.
• Save: Writes Casper workflow to the appropriate directory for your AI tool (e.g., .cursor/rules/, .github/instructions/, or project root).

Example (Share):

{
  "tool": "get_casper_workflow",
  "mode": "share",
  "section": "explore",
  "content": "# 🔍 Casper's Collaborative Exploration Phase...",
  "sections_available": ["explore", "craft", "polish", "full"]
}

Example (Save):

{
  "tool": "get_casper_workflow",
  "mode": "save",
  "section": "explore",
  "tool_context": "cursor",
  "file_path": "/path/to/project/.cursor/rules/casper-explore.mdc",
  "status": "success"
}

Integration: Casper workflow files are auto-saved in the correct format and location for Cursor, VS Code, or generic tools. Tool context is detected automatically.

Phases:

• Explore: Analysis & planning
• Craft: TDD implementation
• Polish: Quality refinement

For IT Teams

This MCP server:

• Uses standard MCP protocol (JSON-RPC 2.0 over stdin/stdout)
• Supports API key authentication
• No data stored locally - all queries go to your Haiven server
• Works with any MCP-compatible AI tool
• Multi-architecture Docker support (AMD64 and ARM64)

Deployment Options

• Docker: Container available for enterprise deployment (recommended)
• Individual install: Users run Docker commands on their machines
• Centralized: Deploy via software distribution systems

Setup Resources

• VS Code MCP Servers - Comprehensive VS Code guide
• Claude Code MCP - Official Claude documentation
• Cursor MCP Setup - Cursor-specific instructions
• MCP Protocol Overview - General MCP concepts

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Pre-commit hooks: Install with pip install pre-commit && pre-commit install

Testing: Run tests with poetry run pytest tests/ -v

Privacy

The MCP server implementation does not collect, process, or transmit any client-specific data, user inputs, conversation history, or session information. It operates purely as a content delivery mechanism for accessing the Haiven prompt library. Unlike the Haiven web interface, prompts execute through your AI tool's configured LLM (not your enterprise's controlled deployment). Ensure your AI tool usage complies with organizational policies.

License

Licensed under the same terms as the main Haiven project.