​
Overview

Adds a server from the ToolRouter marketplace to an existing stack. You can specify which tools to enable when adding the server, or enable all tools at once.

​
Endpoint

POST https://api.toolrouter.ai/v1/stacks/{stack_id}/servers

​
Authentication

This endpoint requires an API key. Include it in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
stack_id
string
required
The unique identifier of the stack to add the server to

​
Request Body

​
server_id
string
required
The unique identifier of the server to add to the stack
​
enable_all_tools
boolean
default:"false"
Whether to enable all available tools for this server
​
enabled_tools
array
Array of specific tool IDs to enable. Only used if enable_all_tools is false.

​
Response

​
message
string
Confirmation message indicating the server was added successfully and how many tools were enabled

​
Example Request

​
Add Server with All Tools Enabled

curl -X POST "https://api.toolrouter.ai/v1/stacks/stack_123e4567-e89b-12d3-a456-426614174000/servers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "gmail",
    "enable_all_tools": true
  }'

​
Add Server with Specific Tools

curl -X POST "https://api.toolrouter.ai/v1/stacks/stack_123e4567-e89b-12d3-a456-426614174000/servers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "gmail",
    "enable_all_tools": false,
    "enabled_tools": ["gmail_send_email", "gmail_search_emails"]
  }'

​
Add Server with No Tools (Configure Later)

curl -X POST "https://api.toolrouter.ai/v1/stacks/stack_123e4567-e89b-12d3-a456-426614174000/servers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "gmail",
    "enable_all_tools": false
  }'

​
Example Responses

​
All Tools Enabled

{
  "message": "Server gmail added to stack stack_123e4567-e89b-12d3-a456-426614174000 with 5 tools enabled"
}

​
Specific Tools Enabled

{
  "message": "Server gmail added to stack stack_123e4567-e89b-12d3-a456-426614174000 with 2 tools enabled"
}

​
No Tools Enabled

{
  "message": "Server gmail added to stack stack_123e4567-e89b-12d3-a456-426614174000 with 0 tools enabled"
}

​
Workflow

After adding a server to a stack:
  1. Configure credentials: Use the Update Credentials endpoint to add required credentials
  2. Enable/disable tools: Use the Update Server Tools endpoint to modify enabled tools
  3. Test tools: Use the Invoke Tool endpoint to test functionality

​
Error Responses

​
400 Bad Request
Server already exists in stack or invalid parameters
{
  "detail": "Server gmail already exists in stack"
}
​
401 Unauthorized
Invalid or missing API key
{
  "detail": "Unauthorized"
}
​
404 Not Found
Stack or server not found
{
  "detail": "Stack not found"
}

{
  "detail": "Server gmail not found"
}
​
429 Too Many Requests
Rate limit exceeded
{
  "detail": "Too many requests"
}
​
500 Internal Server Error
Server error occurred
{
  "detail": "Failed to add server to stack"
}

​
Best Practices

  • Check server availability: Use the List Servers endpoint to see available servers and their tools
  • Plan tool selection: Review tool descriptions and parameters before enabling
  • Start with specific tools: Consider enabling only the tools you need rather than all tools
  • Configure credentials early: Add required credentials immediately after adding the server