​
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