Servers

---

​

Get All Servers

Retrieves a list of all configured MCP servers, including their status and available tools.

• Endpoint: /api/servers
• Method: GET
• Response:
  {
    "success": true,
    "data": [
      {
        "name": "example-server",
        "status": "connected",
        "tools": [
          {
            "name": "tool1",
            "description": "Description of tool 1"
          }
        ],
        "config": {
          "type": "stdio",
          "command": "node",
          "args": ["server.js"]
        }
      }
    ]
  }
  

---

​

Get a Server

Returns the configuration of a single server, including upstream tools/prompts/resources when connected.

• Endpoint: GET /api/servers/:name
• Authentication: Required.
• Returns 404 if the server is not configured.

---

​

Create a New Server

Adds a new MCP server to the configuration.

• Endpoint: /api/servers
• Method: POST
• Body:
  {
    "name": "my-new-server",
    "config": {
      "type": "stdio",
      "command": "python",
      "args": ["-u", "my_script.py"],
      "owner": "admin"
    }
  }
  
  • name (string, required): The unique name for the server.
  • config (object, required): The server configuration object.
    • type (string): stdio, sse, streamable-http, or openapi.
    • command (string): Command to execute for stdio type.
    • args (array of strings): Arguments for the command.
    • url (string): URL for sse, streamable-http, or openapi types.
    • openapi (object): OpenAPI configuration.
      • url (string): URL to the OpenAPI schema.
      • schema (object): The OpenAPI schema object itself.
    • headers (object): Headers to send with requests for sse, streamable-http, and openapi types.
    • keepAliveInterval (number): Health check and reconnect interval in milliseconds for remote servers. Defaults to 60000.
    • enableKeepAlive (boolean): Toggle periodic health checks and automatic reconnect attempts for remote servers.
    • enabled (boolean): Defaults to true. Disabled servers stay in the configuration but are not connected.
    • owner (string): The owner of the server. Defaults to the current user or 'admin'.
    • passthroughHeaders (string[]): Inbound HTTP header names that should be forwarded to the upstream server.
    • oauth, proxy, options, description: Optional advanced settings — see MCP Settings.

---

​

Batch Create Servers

Create several servers in a single request. The body contains a servers array of { name, config } objects — the same shape POST /api/servers accepts, just batched:

• Endpoint: POST /api/servers/batch
• Authentication: Required.
• Body:
  {
    "servers": [
      { "name": "fetch", "config": { "type": "stdio", "command": "uvx", "args": ["mcp-server-fetch"] } },
      { "name": "amap", "config": { "type": "sse", "url": "https://mcp.amap.com/sse?key=..." } }
    ]
  }
  

Each element is validated independently, and the response contains a per-server { name, success, message? } record so partial batches do not abort the whole request.

---

​

Update a Server

Updates the configuration of an existing MCP server.

• Endpoint: /api/servers/:name
• Method: PUT
• Parameters:
  • :name (string, required): The name of the server to update.
• Body:
  {
    "config": {
      "type": "stdio",
      "command": "node",
      "args": ["new_server.js"]
    }
  }
  
  • config (object, required): The updated server configuration object. See “Create a New Server” for details.

---

​

Delete a Server

Removes an MCP server from the configuration.

• Endpoint: /api/servers/:name
• Method: DELETE
• Parameters:
  • :name (string, required): The name of the server to delete.

---

​

Toggle a Server

Enables or disables an MCP server.

• Endpoint: /api/servers/:name/toggle
• Method: POST
• Parameters:
  • :name (string, required): The name of the server to toggle.
• Body:
  {
    "enabled": true
  }
  
  • enabled (boolean, required): true to enable the server, false to disable it.

---

​

Reload a Server

Forces MCPHub to disconnect and re-establish the upstream connection (or re-spawn the stdio child) for a single server. Use this when an upstream server has been updated out-of-band or appears stuck.

• Endpoint: POST /api/servers/:name/reload
• Authentication: Required.

---

​

Toggle a Tool

Enables or disables a specific tool on a server.

• Endpoint: /api/servers/:serverName/tools/:toolName/toggle
• Method: POST
• Parameters:
  • :serverName (string, required): The name of the server.
  • :toolName (string, required): The name of the tool.
• Body:
  {
    "enabled": true
  }
  
  • enabled (boolean, required): true to enable the tool, false to disable it.

---

​

Update Tool Description

Updates the description of a specific tool.

• Endpoint: /api/servers/:serverName/tools/:toolName/description
• Method: PUT
• Parameters:
  • :serverName (string, required): The name of the server.
  • :toolName (string, required): The name of the tool.
• Body:
  {
    "description": "New tool description"
  }
  
  • description (string, required): The new description for the tool.

---

​

Reset Tool Description

Drops the override stored in MCPHub and falls back to the upstream tool description.

• Endpoint: DELETE /api/servers/:serverName/tools/:toolName/description
• Authentication: Required.

---

​

Prompts

MCPHub exposes the same toggle / describe / reset triple for upstream prompts. The body shape mirrors the tool endpoints above.

---

​

Resources

---

​

System Configuration

System-wide configuration (routing, install, smart routing, mcpRouter, name separator, session rebuild, OAuth server) is managed through PUT /api/system-config. See System Config API for the full request schema and accepted top-level keys (routing, install, smartRouting, mcpRouter, nameSeparator, enableSessionRebuild, oauthServer).

---

​

Get Settings

Retrieves all server settings and configurations.

• Endpoint: /api/settings
• Method: GET
• Response:
  {
    "success": true,
    "data": {
      "servers": [...],
      "groups": [...],
      "systemConfig": {...}
    }
  }
  

Note: For built-in prompt and resource management (not tied to an upstream server), see the Prompts API documentation.

---

​

Other server-adjacent endpoints

MCPHub exposes several other route families beyond pure server CRUD. Each lives on its own resource and is documented separately or, where no dedicated page exists yet, follows the schema described inline: