# MCP Server API Reference > **⚠️ DEPRECATION NOTICE** > > This MCP server is **EXPERIMENTAL** and **NOT ACTIVELY MAINTAINED**. > > The author currently manages prompts through slash commands and meta-commands > in the hexai agent system, making this MCP server redundant for its original > purpose. This code is kept for potential future enhancements (possibly with > different functionality beyond prompt management), but no guarantees are made > about stability or continued support. > > **This documentation is preserved for reference only.** The hexai-mcp-server implements the Model Context Protocol with prompt management extensions. ## Protocol Version **Version**: `2025-06-18` ## Server Capabilities The server advertises these capabilities during initialization: ```json { "capabilities": { "prompts": { "listChanged": false, "mutable": true } } } ``` - `listChanged`: Server does not currently emit notifications when prompts change - `mutable`: **Server supports create/update/delete operations** ## Standard MCP Methods ### initialize Establishes connection and negotiates capabilities. **Request:** ```json { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "my-client", "version": "1.0.0" } } } ``` **Response:** ```json { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-06-18", "capabilities": { "prompts": { "listChanged": false, "mutable": true } }, "serverInfo": { "name": "hexai-mcp-server", "version": "0.19.0" } } } ``` ### prompts/list Lists all available prompts with pagination support. **Request:** ```json { "jsonrpc": "2.0", "id": 2, "method": "prompts/list", "params": { "cursor": "" } } ``` **Response:** ```json { "jsonrpc": "2.0", "id": 2, "result": { "prompts": [ { "name": "code_review", "title": "Request Code Review", "description": "Analyzes code quality, style, and suggests improvements", "arguments": [ { "name": "code", "description": "The code to review", "required": true } ] } ], "nextCursor": "" } } ``` ### prompts/get Retrieves a specific prompt with argument rendering. **Request:** ```json { "jsonrpc": "2.0", "id": 3, "method": "prompts/get", "params": { "name": "code_review", "arguments": { "code": "function hello() { console.log('world'); }" } } } ``` **Response:** ```json { "jsonrpc": "2.0", "id": 3, "result": { "description": "Analyzes code quality, style, and suggests improvements", "messages": [ { "role": "user", "content": { "type": "text", "text": "Please review the following code for quality, style, and potential issues:\n\nfunction hello() { console.log('world'); }" } } ] } } ``` ## Management Methods (Extension) These methods are **hexai-mcp-server extensions** that allow prompt management through the MCP protocol. ### prompts/create Creates a new custom prompt. **Request:** ```json { "jsonrpc": "2.0", "id": 4, "method": "prompts/create", "params": { "name": "api_design", "title": "Design REST API", "description": "Creates RESTful API endpoint specification", "arguments": [ { "name": "resource", "description": "Resource name (e.g., users, posts)", "required": true } ], "messages": [ { "role": "user", "content": { "type": "text", "text": "Design a REST API for: {{resource}}" } } ], "tags": ["api", "rest", "design"] } } ``` **Response:** ```json { "jsonrpc": "2.0", "id": 4, "result": { "success": true, "message": "Created prompt: api_design" } } ``` **Required Fields:** - `name`: Unique identifier (alphanumeric + underscores) - `title`: Display name - `messages`: At least one message **Optional Fields:** - `description`: Human-readable description - `arguments`: Template variables - `tags`: Categorization tags ### prompts/update Updates an existing custom prompt. **Request:** ```json { "jsonrpc": "2.0", "id": 5, "method": "prompts/update", "params": { "name": "api_design", "title": "Design RESTful API (Updated)", "description": "Creates comprehensive RESTful API specification with best practices" } } ``` **Response:** ```json { "jsonrpc": "2.0", "id": 5, "result": { "success": true, "message": "Updated prompt: api_design" } } ``` **Required Fields:** - `name`: Prompt identifier **Optional Fields** (only provided fields are updated): - `title`: New title - `description`: New description - `arguments`: New arguments (replaces entire list) - `messages`: New messages (replaces entire list) - `tags`: New tags (replaces entire list) ### prompts/delete Deletes a custom prompt. **Request:** ```json { "jsonrpc": "2.0", "id": 6, "method": "prompts/delete", "params": { "name": "old_prompt" } } ``` **Response:** ```json { "jsonrpc": "2.0", "id": 6, "result": { "success": true, "message": "Deleted prompt: old_prompt" } } ``` **Note**: Can only delete custom prompts from `user.jsonl`, not built-in prompts from `default.jsonl`. ## Error Responses All methods return standard JSON-RPC 2.0 errors: ```json { "jsonrpc": "2.0", "id": 7, "error": { "code": -32602, "message": "Prompt name is required" } } ``` ### Error Codes | Code | Meaning | Example | |------|---------|---------| | -32700 | Parse error | Invalid JSON | | -32600 | Invalid request | Malformed request structure | | -32601 | Method not found | Unknown method | | -32602 | Invalid params | Missing required field | | -32603 | Internal error | Database/storage error | ## Template Syntax Prompts support template variables using `{{variable}}` syntax: ```json { "text": "Review this {{language}} code:\n\n{{code}}" } ``` When rendered with arguments `{"language": "Go", "code": "..."}`: ``` Review this Go code: ... ``` ## Example: Full Workflow ```javascript // 1. Initialize send({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "my-client", version: "1.0" } } }); // 2. List prompts send({ jsonrpc: "2.0", id: 2, method: "prompts/list" }); // 3. Create custom prompt send({ jsonrpc: "2.0", id: 3, method: "prompts/create", params: { name: "perf_analysis", title: "Performance Analysis", arguments: [{ name: "code", required: true }], messages: [ { role: "user", content: { type: "text", text: "Analyze performance: {{code}}" } } ], tags: ["performance"] } }); // 4. Use the prompt send({ jsonrpc: "2.0", id: 4, method: "prompts/get", params: { name: "perf_analysis", arguments: { code: "for i := 0; i < n; i++ { ... }" } } }); // 5. Update prompt send({ jsonrpc: "2.0", id: 5, method: "prompts/update", params: { name: "perf_analysis", description: "Enhanced performance analysis with profiling suggestions" } }); // 6. Delete prompt send({ jsonrpc: "2.0", id: 6, method: "prompts/delete", params: { name: "perf_analysis" } }); ``` ## Client Implementation Notes ### Capability Detection Check for `mutable: true` in server capabilities: ```javascript const initResult = await initialize(); const canManage = initResult.capabilities.prompts?.mutable === true; if (canManage) { // Show create/edit/delete UI } ``` ### Error Handling Always check for errors in responses: ```javascript const response = await request("prompts/create", params); if (response.error) { console.error(`Error ${response.error.code}: ${response.error.message}`); return; } if (response.result.success) { console.log(response.result.message); } ``` ### Immediate Effect Changes take effect immediately: - Create/update/delete operations modify `user.jsonl` - Next `prompts/list` or `prompts/get` reflects changes - No server restart required ### Built-in vs Custom - **Built-in prompts**: Cannot be modified or deleted - **Custom prompts**: Stored in `user.jsonl`, fully manageable - Attempting to delete/update built-in prompts returns an error ## Testing with curl ```bash # Initialize echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | hexai-mcp-server # Create prompt cat <