Valarchi
How It Works
Model Context Protocol

MCP Server Usage Guide

Integrate Valarchi task management with AI coding agents like Cursor, Claude Code, and VS Code. Access your product requirements and task lists directly from your IDE.

Installation

Install the Valarchi Task MCP Server using npm
Quick Install
npx @valarchi/task-mcp-server

The MCP server will be installed and run automatically when configured in your IDE.

Quick Setup

Use the interactive setup script for the easiest configuration experience
Running the Setup Script
1

If you've cloned the repository:

npm run setup

Or run directly: node setup.js

2

If installed via npm:

npx valarchi-mcp-setup

The setup script will guide you through the configuration process

Setup Process
1

Choose your IDE/tool: Cursor, VS Code, Claude Code, or Other

2

Enter your credentials: API key, API URL, and Product ID

3

Get your configuration file ready to paste into your IDE settings

IDE-Specific Setup

Follow the instructions for your specific IDE or coding tool

Cursor

Configure the MCP server in Cursor settings
Setup Steps
1

Run the setup script and select option 1 (Cursor)

2

Copy the contents of the generated cursor-config.json file

3

Open Cursor Settings → Features → Model Context Protocol

4

Paste the configuration into your MCP settings

5

Restart Cursor

Configuration
{
  "mcpServers": {
    "valarchi-tasks": {
      "command": "npx",
      "args": ["@valarchi/task-mcp-server"],
      "env": {
        "PRODUCT_ID": "your-product-id",
        "VALARCHI_API_KEY": "your-api-key-here"
      }
    }
  }
}

VS Code

Configure the MCP server using an MCP extension
Setup Steps
1

Run the setup script and select option 2 (VS Code)

2

Copy the contents of the generated vscode-config.json file

3

Install an MCP extension for VS Code (if not already installed)

4

Open VS Code Settings → MCP Servers

5

Paste the configuration into your MCP settings

6

Reload VS Code

Configuration
{
  "mcp.servers": {
    "valarchi-tasks": {
      "command": "npx",
      "args": ["@valarchi/task-mcp-server"],
      "env": {
        "PRODUCT_ID": "your-product-id",
        "VALARCHI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code (CLI)

Configure the MCP server for Claude Code CLI
Setup Steps
1

Run the setup script and select option 3 (Claude Code)

2

Copy the contents of the generated claude-config.json file

3

Add the configuration to your Claude Code MCP settings

4

Restart Claude Code

Configuration
{
  "mcpServers": {
    "valarchi-tasks": {
      "command": "npx",
      "args": ["@valarchi/task-mcp-server"],
      "env": {
        "PRODUCT_ID": "your-product-id",
        "VALARCHI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Other Tools

Configure for any MCP-compatible tool
Using the Setup Script (Recommended)
1

Run the setup script and select option 4 (Other)

2

The configuration will be saved to ~/.valarchi/config.json

3

The MCP server will automatically load this configuration when environment variables are not set

4

No additional configuration needed - just run the MCP server!

Configuration File Format

If you prefer to create the ~/.valarchi/config.json file manually, use this format:

{
  "PRODUCT_ID": "your-product-id-here",
  "VALARCHI_API_KEY": "your-api-key-here"
}

File locations:
• macOS/Linux: ~/.valarchi/config.json
• Windows: %USERPROFILE%\.valarchi\config.json

Getting Your API Key

Generate an API key from your Valarchi account settings
1

Log in to your Valarchi account

2

Navigate to the API Keys page (or go to /user/settings/api-keys)

3

Click "Generate" to create a new API key

4

Copy the API key immediately - it will only be shown once

5

Store the key securely (e.g., in a password manager or environment variable)

Available Tools

The MCP server provides these tools for accessing your Valarchi tasks
get_task_list

Get the complete task list for your product

Example:

Show me the task list from Valarchi
get_task_details

Get detailed information about a specific task including functional requirements, UI requirements, technical details, testing requirements, and observability needs

Example:

Show me details for task [task-id] from Valarchi
get_task_dependencies

Check the dependencies for a specific task

Example:

What are the dependencies for task [task-id]?

Resources

The server exposes the following resources for accessing task data

valarchi://product/{productId}/tasks

Complete task list for your product

valarchi://product/{productId}/tasks/{taskId}

Individual task details

Example Prompts

Try these prompts in your AI coding agent to interact with Valarchi tasks
Get all tasks
Show me the task list from Valarchi for this product
Get specific task
Show me details for task task-123 from Valarchi
Implement a task
Implement task task-123 from the Valarchi task list. Follow the functional requirements, UI requirements, and technical details provided.
Check dependencies
What are the dependencies for task task-123? Have they been completed?

Troubleshooting

Common issues and solutions
Server not connecting

Verify that VALARCHI_API_URL, PRODUCT_ID, and VALARCHI_API_KEY are set correctly

Check that your Valarchi instance is accessible

Restart your IDE after configuration changes

Invalid API key error

Verify your API key is correct (check for typos or extra spaces)

Ensure the API key hasn't been revoked (check the API Keys page)

Generate a new API key if needed

No tasks showing

Ensure the product has a generated task list

Verify the product ID is correct

Check that the API key belongs to the user who owns the product

Check the server logs for errors

Ready to Integrate?

Connect your Valarchi tasks with your AI coding agent and start building with full context.
Go to Products
Valarchi

Building products the structured way. Stop vibe-coding, start engineering.

Contact Us
Products

Product Requirements

App Structure

Wireframes

Design System

App Icon

Technical Plan

Task List

Resources

Documentation

API Reference