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.