Skip to main content

# API Reference

The vMCP backend provides a comprehensive REST API for managing vMCPs, MCP servers, and monitoring usage.

## Base URL​

    http://localhost:8000/api

## Authentication​

The OSS version uses a dummy user system. All requests operate with `user_id=1`. No authentication headers required.

## vMCP Management​

### List vMCPs​

    GET /api/vmcps

Returns all vMCPs for the user.

Response:

    [
      {
        "vmcp_id": "vmcp_123",
        "name": "Development vMCP",
        "description": "For local development tasks",
        "mcp_servers": [
          {
            "server_id": "server_456",
            "name": "filesystem",
            "priority": 1
          }
        ],
        "active_config": {},
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ]

### Get vMCP​

    GET /api/vmcps/{vmcp_id}

Returns details of a specific vMCP.

### Create vMCP​

    POST /api/vmcps

Request Body:

    {
      "name": "My vMCP",
      "description": "Description of the vMCP",
      "mcp_servers": [
        {
          "server_id": "server_123",
          "priority": 1
        }
      ],
      "active_config": {
        "api_key": "value"
      }
    }

Response:

    {
      "vmcp_id": "vmcp_789",
      "name": "My vMCP",
      "description": "Description of the vMCP",
      "mcp_servers": [...],
      "active_config": {...},
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }

### Update vMCP​

    PUT /api/vmcps/{vmcp_id}

Request Body: Same as create vMCP

### Delete vMCP​

    DELETE /api/vmcps/{vmcp_id}

Response:

    {
      "message": "vMCP deleted successfully"
    }

### Import vMCP​

    POST /api/vmcps/import

Import a vMCP from JSON configuration.

Request Body:

    {
      "name": "Imported vMCP",
      "description": "Imported configuration",
      "mcp_servers": [...],
      "active_config": {...}
    }

### Export vMCP​

    GET /api/vmcps/{vmcp_id}/export

Export a vMCP configuration as JSON.

## MCP Server Management​

### List MCP Servers​

    GET /api/mcp-servers

Returns all MCP servers connected by the user.

Response:

    [
      {
        "server_id": "server_123",
        "name": "filesystem",
        "description": "Local filesystem access",
        "transport_type": "stdio",
        "config": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
        },
        "status": "connected",
        "last_connected": "2024-01-15T10:30:00Z",
        "created_at": "2024-01-15T10:00:00Z"
      }
    ]

### Get MCP Server​

    GET /api/mcp-servers/{server_id}

### Create MCP Server​

    POST /api/mcp-servers

Request Body:

    {
      "name": "github-mcp",
      "description": "GitHub integration",
      "transport_type": "stdio",
      "config": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"]
      }
    }

### Update MCP Server​

    PUT /api/mcp-servers/{server_id}

### Delete MCP Server​

    DELETE /api/mcp-servers/{server_id}

### Connect to MCP Server​

    POST /api/mcp-servers/{server_id}/connect

Establishes connection to the MCP server.

Response:

    {
      "status": "connected",
      "capabilities": {
        "tools": ["list_files", "read_file", "write_file"],
        "resources": ["file://"],
        "prompts": []
      }
    }

### Disconnect from MCP Server​

    POST /api/mcp-servers/{server_id}/disconnect

## vMCP Protocol Operations​

### List Tools​

    GET /api/vmcps/{vmcp_id}/tools

Returns all available tools from the vMCP's connected servers.

Response:

    {
      "tools": [
        {
          "name": "filesystem.read_file",
          "description": "Read a file from the filesystem",
          "inputSchema": {
            "type": "object",
            "properties": {
              "path": {
                "type": "string",
                "description": "File path"
              }
            },
            "required": ["path"]
          }
        }
      ]
    }

### Call Tool​

    POST /api/vmcps/{vmcp_id}/tools/call

Execute a tool through the vMCP.

Request Body:

    {
      "name": "filesystem.read_file",
      "arguments": {
        "path": "/path/to/file.txt"
      }
    }

Response:

    {
      "content": [
        {
          "type": "text",
          "text": "File contents here..."
        }
      ]
    }

### List Resources​

    GET /api/vmcps/{vmcp_id}/resources

Returns all available resources from the vMCP.

### Read Resource​

    POST /api/vmcps/{vmcp_id}/resources/read

Request Body:

    {
      "uri": "file:///path/to/file.txt"
    }

### List Prompts​

    GET /api/vmcps/{vmcp_id}/prompts

Returns all available prompt templates.

### Get Prompt​

    POST /api/vmcps/{vmcp_id}/prompts/get

Request Body:

    {
      "name": "code_review",
      "arguments": {
        "language": "python"
      }
    }

## Stats and Monitoring​

### Get Stats​

    GET /api/stats

Returns usage statistics and logs.

Query Parameters:

- `start_date` (optional) - ISO 8601 date string
- `end_date` (optional) - ISO 8601 date string
- `vmcp_id` (optional) - Filter by vMCP
- `client_id` (optional) - Filter by client
- `method` (optional) - Filter by method (tools/list, tools/call, etc.)
- `page` (optional) - Page number (default: 1)
- `page_size` (optional) - Results per page (default: 50, max: 100)

Response:

    {
      "stats": {
        "total_logs": 1523,
        "active_clients": 3,
        "total_vmcps": 5,
        "total_tool_calls": 847,
        "avg_tools_per_call": 2.3
      },
      "logs": [
        {
          "log_id": "log_123",
          "client_id": "client_456",
          "vmcp_id": "vmcp_789",
          "method": "tools/call",
          "mcp_server_id": "server_101",
          "arguments": {"path": "/file.txt"},
          "result": {"content": [...]},
          "active_config_snapshot": {},
          "timestamp": "2024-01-15T10:30:00Z"
        }
      ],
      "pagination": {
        "page": 1,
        "page_size": 50,
        "total_pages": 31,
        "total_items": 1523
      }
    }

## Error Responses​

All endpoints follow a consistent error response format:

    {
      "error": "Error message",
      "detail": "Detailed error information"
    }

### Common HTTP Status Codes​

- `200 OK` - Request succeeded
- `201 Created` - Resource created successfully
- `400 Bad Request` - Invalid request parameters
- `404 Not Found` - Resource not found
- `500 Internal Server Error` - Server error

## Variable Substitution​

When calling tools, vMCP supports these variable patterns:

- `@param:name` - Runtime parameters from active_config
- `@config:key` - Configuration values
- `@tool(server.tool_name)` - Call another tool and use result
- `@resource(server.uri)` - Read resource and use content
- `@prompt(server.prompt_name)` - Use prompt template

Example:

    {
      "name": "github.create_issue",
      "arguments": {
        "repo": "@config:default_repo",
        "title": "@param:issue_title",
        "body": "@prompt(github.issue_template)"
      }
    }

## WebSocket (Future)​

Real-time updates for server status and logs will be available via WebSocket:

    ws://localhost:8000/ws

Currently not implemented in OSS version.