Groups

---

​

Get All Groups

Retrieves a list of all server groups.

• Endpoint: /api/groups
• Method: GET
• Success Response:
  {
    "success": true,
    "data": [
      {
        "id": "group-1",
        "name": "My Group",
        "description": "A collection of servers.",
        "servers": ["server1", "server2"],
        "owner": "admin"
      }
    ]
  }
  

---

​

Create a New Group

Creates a new server group.

• Endpoint: /api/groups
• Method: POST
• Body:
  • name (string, required): The name of the group.
  • description (string, optional): A description for the group.
  • instructions (string, optional): Sent as the MCP initialize instructions on the group’s routes. See Group instructions.
  • servers (array, optional): A list of server names or capability-scoped server configuration objects.
• Request Example:
  {
    "name": "My New Group",
    "description": "A description for the new group",
    "servers": [
      "server1",
      {
        "name": "server2",
        "tools": ["toolA", "toolB"],
        "prompts": ["draft_prompt"],
        "resources": ["resource://docs/guide"]
      }
    ]
  }
  

---

​

Get a Group

Retrieves details for a specific group by its ID or name.

• Endpoint: /api/groups/:id
• Method: GET
• Parameters:
  • :id (string, required): The ID or name of the group.

---

​

Update a Group

Updates an existing group’s name, description, instructions, or server list.

• Endpoint: /api/groups/:id
• Method: PUT
• Parameters:
  • :id (string, required): The ID or name of the group to update.
• Body:
  • name (string, optional): The new name for the group.
  • description (string, optional): The new description for the group.
  • instructions (string, optional): The new instructions for the group; an empty string removes them.
  • servers (array, optional): The new list of servers for the group. See Batch Update Group Servers for format.
• Request Example:
  {
    "name": "Updated Group Name",
    "description": "Updated description"
  }
  

---

​

Delete a Group

Deletes a group by its ID or name.

• Endpoint: /api/groups/:id
• Method: DELETE
• Parameters:
  • :id (string, required): The ID or name of the group to delete.

---

​

Add Server to Group

Adds a single server to a group.

• Endpoint: /api/groups/:id/servers
• Method: POST
• Parameters:
  • :id (string, required): The ID or name of the group.
• Body:
  • serverName (string, required): The name of the server to add.
• Request Example:
  {
    "serverName": "my-server"
  }
  

---

​

Remove Server from Group

Removes a single server from a group.

• Endpoint: /api/groups/:id/servers/:serverName
• Method: DELETE
• Parameters:
  • :id (string, required): The ID or name of the group.
  • :serverName (string, required): The name of the server to remove.

---

​

Batch Update Group Servers

Replaces all servers in a group with a new list. The list can be simple strings or detailed configuration objects.

• Endpoint: /api/groups/:id/servers/batch
• Method: PUT
• Parameters:
  • :id (string, required): The ID or name of the group.
• Body:
  • servers (array, required): An array of server names (strings) or server configuration objects.
• Request Example (Simple):
  {
    "servers": ["server1", "server2"]
  }
  
• Request Example (Detailed):
  {
    "servers": [
      {
        "name": "server1",
        "tools": "all",
        "prompts": "all",
        "resources": "all"
      },
      {
        "name": "server2",
        "tools": ["toolA", "toolB"],
        "prompts": ["draft_prompt"],
        "resources": ["resource://docs/guide"]
      }
    ]
  }
  

Each detailed server object accepts these optional capability selectors:

• preserveToolNames: a boolean (default false). Expose upstream tool names without a server prefix on group and Smart Routing routes. Names must be unique in the group; prompts and resources are unchanged. See Keep original tool names.
• tools: "all" or an array of tool names.
• prompts: "all" or an array of prompt names.
• resources: "all" or an array of resource URIs.
• pinnedTools: an array of bare tool names listed next to the meta-tools on the group’s $smart/{group} endpoint (see Pinned Tools). Only pins that are also selected in tools take effect.

---

​

Get Group Server Configs

Retrieves the detailed configuration for all servers within a group, including which tools, prompts, and resources are enabled.

• Endpoint: /api/groups/:id/server-configs
• Method: GET
• Parameters:
  • :id (string, required): The ID or name of the group.
• Success Response:
  {
    "success": true,
    "data": [
      {
        "name": "server1",
        "tools": "all",
        "prompts": "all",
        "resources": "all"
      },
      {
        "name": "server2",
        "tools": ["toolA", "toolB"],
        "prompts": ["draft_prompt"],
        "resources": ["resource://docs/guide"]
      }
    ]
  }
  

---

​

Update Group Server Tools

Updates the tool selection for a specific server within a group.

• Endpoint: /api/groups/:id/server-configs/:serverName/tools
• Method: PUT
• Parameters:
  • :id (string, required): The ID or name of the group.
  • :serverName (string, required): The name of the server to update.
• Body:
  • tools (string or array of strings, required): Either the string "all" to enable all tools, or an array of tool names to enable specifically. Pins (pinnedTools) of tools left out of the array are removed.
• Request Example:
  {
    "tools": ["toolA", "toolC"]
  }
  

​

Visibility fields

POST /api/groups, entries in POST /api/groups/batch, and PUT /api/groups/:id accept visibility (private | group | public) and sharedWithUsers (an array of non-empty usernames). New groups default to private; omitted fields on update remain unchanged. shared and null are not valid visibility values. An empty shared user list allows only the owner and admins. GET /api/groups/:id/share-candidates returns a sorted array of usernames, excluding the owner, and requires owner/admin access. Sharing grants discovery/use, not management. All group read responses filter inaccessible nested servers; replacement server edits preserve existing inaccessible entries. See Group Management for legacy compatibility and database upgrade behavior.