API Reference

Complete reference for the MCpeg Model Context Protocol API.

Overview

MCpeg implements the Model Context Protocol (MCP) specification version 2025-03-26 over JSON-RPC 2.0. All API calls use HTTP POST requests to the /mcp endpoint.

Base URL

POST http://localhost:8080/mcp

Authentication

JWT Authentication (Optional)

When JWT authentication is enabled, include the authorization header:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

No Authentication (Development)

For development mode, no authentication is required:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Core MCP Methods

Initialize

Establishes a connection and negotiates capabilities.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {},
      "resources": {},
      "prompts": {}
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {
        "listChanged": true
      },
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "prompts": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "mcpeg",
      "version": "1.0.0"
    }
  }
}

Ping

Health check method to verify server availability.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ping",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "healthy",
    "timestamp": "2024-01-01T12:00:00Z"
  }
}

Tools API

List Tools

Get all available tools from enabled plugins.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "memory_store",
        "description": "Store a key-value pair in persistent memory",
        "inputSchema": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string",
              "description": "The key to store"
            },
            "value": {
              "type": "string",
              "description": "The value to store"
            }
          },
          "required": ["key", "value"]
        }
      },
      {
        "name": "git_status",
        "description": "Show the status of the git repository",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      }
    ]
  }
}

Call Tool

Execute a specific tool with provided arguments.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_store",
    "arguments": {
      "key": "user_preference",
      "value": "dark_mode"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Successfully stored key 'user_preference' with value 'dark_mode'"
      }
    ]
  }
}

Resources API

List Resources

Get all available resources from enabled plugins.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "uri": "file:///README.md",
        "name": "README.md",
        "description": "Project README file",
        "mimeType": "text/markdown"
      },
      {
        "uri": "memory://stored_keys",
        "name": "Memory Keys",
        "description": "List of all stored memory keys",
        "mimeType": "application/json"
      }
    ]
  }
}

Read Resource

Read the contents of a specific resource.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "file:///README.md"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "contents": [
      {
        "uri": "file:///README.md",
        "mimeType": "text/markdown",
        "text": "# MCpeg\n\nModel Context Protocol Enablement Gateway..."
      }
    ]
  }
}

Subscribe to Resource

Subscribe to changes in a resource (if supported).

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/subscribe",
  "params": {
    "uri": "memory://stored_keys"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "subscribed": true
  }
}

Prompts API

List Prompts

Get all available prompt templates.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/list",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "prompts": [
      {
        "name": "code_review",
        "description": "Review code for quality and best practices",
        "arguments": [
          {
            "name": "language",
            "description": "Programming language",
            "required": true
          },
          {
            "name": "context",
            "description": "Code context or purpose",
            "required": false
          }
        ]
      }
    ]
  }
}

Get Prompt

Get a specific prompt template with arguments.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/get",
  "params": {
    "name": "code_review",
    "arguments": {
      "language": "go",
      "context": "web service"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "description": "Review code for quality and best practices",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Please review this Go code for a web service. Focus on code quality, best practices, performance, and security concerns."
        }
      }
    ]
  }
}

Built-in Plugin APIs

Memory Plugin

Store Value

Tool: memory_store

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_store",
    "arguments": {
      "key": "project_config",
      "value": "{\"theme\":\"dark\",\"language\":\"en\"}"
    }
  }
}

Retrieve Value

Tool: memory_retrieve

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_retrieve",
    "arguments": {
      "key": "project_config"
    }
  }
}

List All Keys

Tool: memory_list

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_list",
    "arguments": {}
  }
}

Delete Key

Tool: memory_delete

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_delete",
    "arguments": {
      "key": "project_config"
    }
  }
}

Git Plugin

Git Status

Tool: git_status

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "git_status",
    "arguments": {}
  }
}

Git Commit

Tool: git_commit

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "git_commit",
    "arguments": {
      "message": "Add new feature",
      "add_all": true
    }
  }
}

Git Diff

Tool: git_diff

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "git_diff",
    "arguments": {
      "staged": false
    }
  }
}

Git Log

Tool: git_log

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "git_log",
    "arguments": {
      "limit": 10
    }
  }
}

Editor Plugin

Read File

Tool: file_read

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_read",
    "arguments": {
      "path": "src/main.go"
    }
  }
}

Write File

Tool: file_write

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_write",
    "arguments": {
      "path": "src/example.go",
      "content": "package main\n\nfunc main() {\n    println(\"Hello, World!\")\n}"
    }
  }
}

List Directory

Tool: file_list

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_list",
    "arguments": {
      "path": "src"
    }
  }
}

Delete File

Tool: file_delete

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_delete",
    "arguments": {
      "path": "src/example.go"
    }
  }
}

Administrative APIs

Health Check

Endpoint: GET /health

Response:

{
  "status": "healthy",
  "version": "v1.0.0",
  "uptime": "2h30m15s",
  "timestamp": "2024-01-01T12:00:00Z",
  "components": {
    "gateway": "healthy",
    "plugins": "healthy",
    "memory": "healthy",
    "git": "healthy",
    "editor": "healthy"
  }
}

Metrics

Endpoint: GET /metrics

Response: (Prometheus format)

# HELP mcpeg_requests_total Total number of requests
# TYPE mcpeg_requests_total counter
mcpeg_requests_total{method="tools/call"} 150

# HELP mcpeg_request_duration_seconds Request duration in seconds
# TYPE mcpeg_request_duration_seconds histogram
mcpeg_request_duration_seconds_bucket{method="tools/call",le="0.1"} 120
mcpeg_request_duration_seconds_bucket{method="tools/call",le="0.5"} 145
mcpeg_request_duration_seconds_bucket{method="tools/call",le="1.0"} 150

Plugin Management

List Plugins

Endpoint: GET /admin/plugins

Response:

{
  "plugins": [
    {
      "name": "memory",
      "version": "1.0.0",
      "enabled": true,
      "status": "healthy",
      "description": "Persistent key-value storage service"
    },
    {
      "name": "git",
      "version": "1.0.0",
      "enabled": true,
      "status": "healthy",
      "description": "Git version control operations"
    }
  ]
}

Reload Plugin

Endpoint: POST /admin/plugins/reload

Request:

{
  "plugin_name": "memory"
}

Response:

{
  "success": true,
  "message": "Plugin 'memory' reloaded successfully"
}

Error Handling

Standard JSON-RPC Errors

Parse Error (-32700)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32700,
    "message": "Parse error"
  },
  "id": null
}

Invalid Request (-32600)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request"
  },
  "id": null
}

Method Not Found (-32601)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found"
  },
  "id": 1
}

Invalid Params (-32602)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Missing required parameter: key"
  },
  "id": 1
}

Internal Error (-32603)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "Plugin execution failed"
  },
  "id": 1
}

Custom Application Errors

Plugin Not Found (-32000)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Plugin not found",
    "data": "Plugin 'custom' is not enabled or installed"
  },
  "id": 1
}

Authentication Required (-32001)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Authentication required",
    "data": "JWT token is missing or invalid"
  },
  "id": 1
}

Access Denied (-32002)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32002,
    "message": "Access denied",
    "data": "Insufficient permissions for this operation"
  },
  "id": 1
}

Rate Limiting

MCpeg supports rate limiting to prevent abuse:

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Rate Limit Exceeded Response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32003,
    "message": "Rate limit exceeded",
    "data": "Too many requests. Limit: 100 per minute"
  },
  "id": 1
}

WebSocket Support

MCpeg supports WebSocket connections for real-time communication:

Connection: ws://localhost:8080/ws

WebSocket Message Format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_store",
    "arguments": {
      "key": "test",
      "value": "websocket"
    }
  }
}

SDK Examples

JavaScript/Node.js

const axios = require('axios');

class MCpegClient {
  constructor(baseUrl = 'http://localhost:8080') {
    this.baseUrl = baseUrl;
    this.requestId = 0;
  }

  async call(method, params = {}) {
    const response = await axios.post(`${this.baseUrl}/mcp`, {
      jsonrpc: '2.0',
      id: ++this.requestId,
      method,
      params
    });
    
    if (response.data.error) {
      throw new Error(response.data.error.message);
    }
    
    return response.data.result;
  }

  async initialize() {
    return this.call('initialize', {
      protocolVersion: '2025-03-26',
      capabilities: { tools: {}, resources: {}, prompts: {} }
    });
  }

  async listTools() {
    return this.call('tools/list');
  }

  async callTool(name, arguments) {
    return this.call('tools/call', { name, arguments });
  }
}

// Usage
const client = new MCpegClient();
await client.initialize();
const tools = await client.listTools();
const result = await client.callTool('memory_store', { key: 'test', value: 'hello' });

Python

import requests
import json

class MCpegClient:
    def __init__(self, base_url='http://localhost:8080'):
        self.base_url = base_url
        self.request_id = 0
    
    def call(self, method, params=None):
        self.request_id += 1
        payload = {
            'jsonrpc': '2.0',
            'id': self.request_id,
            'method': method,
            'params': params or {}
        }
        
        response = requests.post(f'{self.base_url}/mcp', json=payload)
        data = response.json()
        
        if 'error' in data:
            raise Exception(data['error']['message'])
        
        return data['result']
    
    def initialize(self):
        return self.call('initialize', {
            'protocolVersion': '2025-03-26',
            'capabilities': {'tools': {}, 'resources': {}, 'prompts': {}}
        })
    
    def list_tools(self):
        return self.call('tools/list')
    
    def call_tool(self, name, arguments):
        return self.call('tools/call', {'name': name, 'arguments': arguments})

# Usage
client = MCpegClient()
client.initialize()
tools = client.list_tools()
result = client.call_tool('memory_store', {'key': 'test', 'value': 'hello'})

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

type MCpegClient struct {
    BaseURL   string
    RequestID int
}

type JSONRPCRequest struct {
    JSONRPC string      `json:"jsonrpc"`
    ID      int         `json:"id"`
    Method  string      `json:"method"`
    Params  interface{} `json:"params"`
}

type JSONRPCResponse struct {
    JSONRPC string      `json:"jsonrpc"`
    ID      int         `json:"id"`
    Result  interface{} `json:"result"`
    Error   *JSONRPCError `json:"error"`
}

type JSONRPCError struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Data    string `json:"data"`
}

func (c *MCpegClient) Call(method string, params interface{}) (interface{}, error) {
    c.RequestID++
    request := JSONRPCRequest{
        JSONRPC: "2.0",
        ID:      c.RequestID,
        Method:  method,
        Params:  params,
    }
    
    body, err := json.Marshal(request)
    if err != nil {
        return nil, err
    }
    
    resp, err := http.Post(c.BaseURL+"/mcp", "application/json", bytes.NewBuffer(body))
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var response JSONRPCResponse
    if err := json.NewDecoder(resp.Body).Decode(&response); err != nil {
        return nil, err
    }
    
    if response.Error != nil {
        return nil, fmt.Errorf("JSON-RPC error: %s", response.Error.Message)
    }
    
    return response.Result, nil
}

// Usage
func main() {
    client := &MCpegClient{BaseURL: "http://localhost:8080"}
    
    // Initialize
    result, err := client.Call("initialize", map[string]interface{}{
        "protocolVersion": "2025-03-26",
        "capabilities": map[string]interface{}{
            "tools": map[string]interface{}{},
        },
    })
    if err != nil {
        panic(err)
    }
    
    // List tools
    tools, err := client.Call("tools/list", nil)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Tools: %v\n", tools)
}

Best Practices

Request Optimization

Batch Requests: Use batch JSON-RPC requests when possible
Connection Reuse: Keep HTTP connections alive
Timeout Handling: Set appropriate timeouts for long-running operations
Error Handling: Always check for JSON-RPC errors

Security

Authentication: Use JWT tokens in production
HTTPS: Always use HTTPS in production
Rate Limiting: Implement client-side rate limiting
Input Validation: Validate all inputs before sending to MCpeg

Performance

Connection Pooling: Use connection pooling for multiple requests
Caching: Cache frequently accessed data
Compression: Enable gzip compression for large payloads
Monitoring: Monitor request latency and error rates

OpenAPI Specification

The complete OpenAPI specification is available at:

File: api/openapi/mcp-gateway.yaml
Endpoint: GET /openapi.json
Documentation: GET /docs (if enabled)

Next Steps

Installation: Installation Guide
Configuration: Configuration Guide
Plugin Development: Plugin Development Guide
Troubleshooting: Troubleshooting Guide

FilesExpand file tree

api-reference.md

Latest commit

History

api-reference.md

File metadata and controls

API Reference

Overview

Base URL

Authentication

JWT Authentication (Optional)

No Authentication (Development)

Core MCP Methods

Initialize

Ping

Tools API

List Tools

Call Tool

Resources API

List Resources

Read Resource

Subscribe to Resource

Prompts API

List Prompts

Get Prompt

Built-in Plugin APIs

Memory Plugin

Store Value

Retrieve Value

List All Keys

Delete Key

Git Plugin

Git Status

Git Commit

Git Diff

Git Log

Editor Plugin

Read File

Write File

List Directory

Delete File

Administrative APIs

Health Check

Metrics

Plugin Management

List Plugins

Reload Plugin

Error Handling

Standard JSON-RPC Errors

Parse Error (-32700)

Invalid Request (-32600)

Method Not Found (-32601)

Invalid Params (-32602)

Internal Error (-32603)

Custom Application Errors

Plugin Not Found (-32000)

Authentication Required (-32001)

Access Denied (-32002)

Rate Limiting

WebSocket Support

SDK Examples

JavaScript/Node.js

Python

Go

Best Practices

Request Optimization

Security

Performance

OpenAPI Specification

Next Steps