Developer Integration: Model Context Protocol (MCP)
Connect Cursor, VS Code, Claude Desktop, Claude Code, and Windsurf to your ARMES workspace using npx armes-mcp and Personal Access Tokens.
What is the ARMES MCP Server?
The Model Context Protocol (MCP) is an open industry standard that connects AI assistants and developer tools to external context, agent systems, and knowledge bases.
With armes-mcp, your local developer environment gains direct, authenticated access to:
- Your AI Agents — chat directly with your custom and marketplace ARMES bots, including real-time streaming and mode routing.
- Persistent Knowledge Base — search, read, create, and update structured notes and nested folders from your editor.
- Vault Files & Documents — search and read extracted text, executive summaries, and chunked contents from PDFs, spreadsheets, and uploaded documents.
- Prompt Templates — resolve prompt templates and their attached context notes directly into your editor's conversation.
- Audit Trail & Sync — conversations initiated through MCP are tagged with
source: 'mcp'and remain visible in your ARMES web and mobile workspace.
Zero Data Retention
Every model call through the ARMES MCP server routes through our zero-data-retention (ZDR) infrastructure. Your code, queries, and file contents are never used to train foundational AI models.
Prerequisites
To use ARMES MCP in your IDE or desktop client, you need:
- An active Pro or Ultra ARMES subscription.
- Node.js 18+ installed on your machine (
node -vin terminal). - A Personal Access Token (PAT) generated from your ARMES settings.
Step 1: Generate a Personal Access Token (PAT)
Personal Access Tokens authenticate your IDE against the ARMES API with scoped permissions.
- Sign in to ARMES and navigate to Settings → Developer.
- Click New Token (or Generate Your First Token).
- Enter a descriptive label (e.g.,
Cursor MacBook Pro,VS Code Desktop). - Select an expiration window (30 days, 60 days, 90 days, or Never).
- Verify the required MCP scopes are selected:
bots:read— View and list available agentsmessages:write— Send prompts and converse with agentsstream:read— Real-time Server-Sent Events (SSE) streaming responsesnotes:read— Search and read knowledge base notes and vault filesnotes:write— Create and edit notes and folders
- Click Generate Token and copy the token starting with
pat_....
Save Your Token Securely
Your token is shown only once upon generation. Treat it like a password. If lost, revoke it and generate a new one.
Step 2: Configure Your IDE or Client
Choose your development environment below for setup instructions:
Cursor IDE
Cursor supports MCP configuration either via a project config file or through the IDE Settings UI.
Option A: Project Configuration File (Recommended)
In the root directory of any project you open in Cursor, create or edit .cursor/mcp.json:
[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],[object Object],
,[object Object],[object Object], ,[object Object],[object Object],[object Object], ,[object Object],[object Object],[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],
,[object Object],
,[object Object],
,[object Object],Option B: Cursor Settings UI
- Open Cursor Settings (
Cmd+,on macOS orCtrl+,on Windows/Linux). - Navigate to Features → MCP Servers.
- Click Add New MCP Server.
- Configure the fields:
- Name:
armes - Type:
command - Command:
npx -y armes-mcp - Environment Variables:
[object Object], ,[object Object],[object Object], ,[object Object],[object Object], ,[object Object],[object Object], ,[object Object], ,[object Object],
- Name:
- Click Save and then Refresh. Green indicators will appear next to the 14 available ARMES tools.
VS Code (Cline, Roo Code, Claude Dev)
If you use VS Code with extensions like Cline, Roo Code, or Claude Dev:
- Create or edit
.vscode/mcp.jsonin your workspace root:
[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],[object Object],
,[object Object],[object Object], ,[object Object],[object Object],[object Object], ,[object Object],[object Object],[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],
,[object Object],
,[object Object],
,[object Object],- Reload your MCP extension or click the refresh button in the MCP server panel.
Claude Desktop
To connect the standalone Claude Desktop app to ARMES:
- Open your Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Add
armesto themcpServersobject:
[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],[object Object],
,[object Object],[object Object], ,[object Object],[object Object],[object Object], ,[object Object],[object Object],[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],
,[object Object],
,[object Object],
,[object Object],- Restart Claude Desktop. The hammer tool icon will display all ARMES tools.
Claude Code (Terminal CLI)
To add ARMES tools to Anthropic's claude CLI:
claude mcp add armes -e ARMES_API_BASE=,[object Object], -e ARMES_PAT=,[object Object], -- npx -y armes-mcpVerify the tools are active:
claude mcp listWindsurf IDE (Codeium)
- Open or create
~/.codeium/windsurf/mcp_config.json:
[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],[object Object],
,[object Object],[object Object], ,[object Object],[object Object],[object Object], ,[object Object],[object Object],[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],[object Object], ,[object Object],[object Object],
,[object Object],[object Object], ,[object Object],
,[object Object],
,[object Object],
,[object Object],
,[object Object],- Restart Windsurf or reload the Cascade panel.
Configuration Reference
The ARMES MCP server accepts configuration through environment variables or CLI flags:
| Variable | CLI Flag | Required | Default | Description |
|---|---|---|---|---|
ARMES_API_BASE | --api-base | Yes | — | Base URL of your ARMES deployment (e.g., https://armes.ai) |
ARMES_PAT | --token | Yes | — | Personal Access Token starting with pat_... |
CLI Test Command
You can test your connection in any terminal before configuring an IDE:
ARMES_PAT=,[object Object], ARMES_API_BASE=,[object Object], npx -y armes-mcp(If valid, the server starts silently and waits for JSON-RPC messages on standard input).
Available Tools (14 Tools)
Once connected, your AI assistant can invoke the full suite of ARMES capabilities:
1. Agents & Conversations
| Tool | Description | Example Prompt |
|---|---|---|
list_bots | Lists all ARMES bots accessible to your account, showing IDs, descriptions, and streaming support. | "What agents are available in my ARMES workspace?" |
send_message | Sends a message to a bot thread with full model modes and streaming support. Creates a new chat or continues an existing one. | "Send this TypeScript compiler error to @code-architect for a diagnosis." |
get_chats | Fetches recent conversations for a specific bot with IDs and previews. | "Show my recent chats with @data-analyst." |
get_messages | Retrieves message history from a specific chat with sender roles and timestamps. | "Pull the last 10 messages from chat ID c8f1-..." |
2. Knowledge Base & Notes
| Tool | Description | Example Prompt |
|---|---|---|
search_notes | Searches note titles and markdown contents across your workspace. | "Search my ARMES notes for 'Stripe webhook replay attack mitigation'." |
read_note | Fetches full markdown content and tags of a specific note by ID. | "Read my note on 'Database Migration Checklist' and check my SQL script." |
list_folders | Inspects your note folder hierarchy (names, parent folders, IDs). | "List my ARMES note folders to find where engineering docs belong." |
create_folder | Creates a new note folder with optional color and parent hierarchy. | "Create a folder named 'Refactor 2026' under Architecture." |
list_notes | Lists all note titles and IDs inside a specific folder. | "What notes are inside folder ID abc-123?" |
create_note | Creates a new markdown note in a designated folder. | "Summarize this architectural decision and save it as a note in my Backend folder." |
update_note | Updates title, content, tags, starred status, or folder placement of an existing note. | "Append this new benchmark result to my 'Engine Performance' note." |
3. Vault Files & Document Intelligence
| Tool | Description | Example Prompt |
|---|---|---|
search_files | Searches persistent uploaded vault documents (PDFs, docs, spreadsheets) by title, OCR text, and summaries. | "Find documents in my library that discuss SOC2 compliance policies." |
read_file | Reads vault file content with selectable modes: summary (default), full (entire text), chunk (sliced window for large files), or metadata. | "Read the executive summary of our architecture whitepaper (file ID xyz)." |
4. Prompt Engineering & Templates
| Tool | Description | Example Prompt |
|---|---|---|
list_templates | Lists all prompt templates with IDs, slash command shortcuts, and previews. | "List my saved ARMES prompt templates." |
Browsable Resources
ARMES MCP exposes your notes and folders as browsable MCP Resources. In clients that support resource inspection (like Cursor's MCP panel), you can attach them directly as persistent context:
| Resource URI | Description |
|---|---|
armes://knowledge-base | High-level hierarchical overview of all your folders and structure. |
armes://folders/{folderId} | Listing of all notes contained in a specific folder. |
armes://notes/{noteId} | Full markdown contents of a specific note. |
Prompt Templates (armes-template)
The MCP server exposes ARMES prompt templates through the MCP Prompts protocol:
- Prompt Name:
armes-template - Arguments:
templateId(obtainable vialist_templates) - How it works: When invoked, ARMES automatically loads the template text and resolves all attached context notes into context messages for the AI model.
Troubleshooting & FAQ
❌ Error: ARMES_API_BASE is required
You must supply the ARMES_API_BASE environment variable or --api-base flag (e.g. https://armes.ai). Ensure your .cursor/mcp.json or .vscode/mcp.json has the env object configured.
❌ Error: Invalid token format
Tokens must start with pat_. Check for accidental spaces or missing characters when pasting.
401 Unauthorized
Your Personal Access Token may have expired or been revoked. Visit Settings → Developer on ARMES to create a new token.
403 Forbidden: Pro or Ultra subscription required
The MCP developer integration is available on Pro and Ultra tiers. If your subscription is on the Free or Eco plan, upgrade your account to enable external API and MCP access.
403 Forbidden: Missing required scopes
Your token is missing the permissions required for that action. When generating a token, ensure you grant bots:read, messages:write, stream:read, notes:read, and notes:write.
Does MCP support streaming responses?
Yes. When sending messages to bots configured with streaming webhooks, armes-mcp automatically handles Server-Sent Events (SSE) and streams the response directly to your assistant.