# Add Tools

> How to add MCP servers, skills, and functions to a workspace, and how tool namespacing works.

A workspace's power comes from the tools inside it. You can add MCP servers from the marketplace, your own external servers, workflow skills, and community functions. Every tool you add is instantly available to all connected clients.

---

## How Adding Tools Works

```mermaid
flowchart LR
    WS["Workspace"] --> S1["GitHub MCP\n5 tools"]
    WS --> S2["Stripe MCP\n12 tools"]
    WS --> S3["Custom Function\n1 tool"]
    WS --> S4["Notion MCP\n8 tools"]

    style WS fill:#3b82f6,stroke:#2563eb,color:#fff
    style S1 fill:#1e293b,stroke:#6b7280,color:#fff
    style S2 fill:#1e293b,stroke:#6b7280,color:#fff
    style S3 fill:#1e293b,stroke:#6b7280,color:#fff
    style S4 fill:#1e293b,stroke:#6b7280,color:#fff
```

When you add a server to a workspace, its tools become part of the workspace's unified tool list. A client calling `tools/list` on the gateway sees tools from all enabled servers merged together. Adding or removing a server takes effect immediately -- no restarts, no redeployments.

---

## Types of Tools

| Type | Source | Example |
|------|--------|---------|
| **Community MCP Servers** | Published on the [Aerostack Hub](/hub) marketplace | GitHub, Stripe, Notion, Linear |
| **External MCP Servers** | Your own MCP server running anywhere | A custom server at `https://my-api.com/mcp` |
| **Skills** | Workflow-powered tools deployed to Aerostack | A "daily digest" skill that aggregates data |
| **Functions** | Community functions from the marketplace | A currency converter, a sentiment analyzer |

---

## Add a Server via Dashboard

1. **Open Your Workspace**

   Navigate to **Workspaces** in the Admin dashboard and select the workspace you want to add tools to.

1. **Browse Available Servers**

   Click **Add Server**. You will see a list of available MCP servers -- community servers from the marketplace, your own published servers, and any team servers shared with you.

1. **Select a Server**

   Click a server to add it. If the server requires API keys or tokens to function, you will be prompted to configure [secrets](/workspaces/secrets).

1. **Configure Secrets (If Needed)**

   If the server needs credentials (for example, a GitHub server needs a `GITHUB_TOKEN`), select which workspace secrets to inject. You can create new secrets on the spot or use existing ones.

1. **Done**

   The server is added and its tools are immediately available to all connected clients. There is no need to reconnect or restart anything -- the next `tools/list` call will include the new tools.

---

## Add a Server via CLI

```bash
# Add a community MCP server by its slug
aerostack workspace server add my-workspace @aerostack/github

# Add with secret injection
aerostack workspace server add my-workspace @aerostack/github --secrets GITHUB_TOKEN

# Add a community function (auto-wrapped as a tool)
aerostack workspace function add my-workspace my-function-slug
```

---

## Tool Namespacing

When multiple servers expose tools with the same name (for example, both a GitHub and GitLab server might have a `create_issue` tool), collisions would occur. The gateway prevents this by namespacing every tool:

```
{serverSlug}__{toolName}
```

**Examples:**

| Server Slug | Original Tool | Namespaced Tool |
|-------------|--------------|-----------------|
| `github` | `create_issue` | `github__create_issue` |
| `gitlab` | `create_issue` | `gitlab__create_issue` |
| `stripe` | `create_customer` | `stripe__create_customer` |
| `my-function` | `run` | `my-function__run` |

The double underscore (`__`) is the delimiter. When you call `tools/call` with the namespaced name, the gateway strips the prefix, routes to the correct upstream server, and returns the result.

  You always use the namespaced tool name when calling tools. LLM clients like Claude Desktop and Cursor handle this automatically -- they see the namespaced names in the tool list and use them in calls.

---

## Enable and Disable Servers

You can temporarily disable a server without removing it from the workspace. A disabled server's tools are excluded from `tools/list` and `tools/call`.

This is useful when:
- A server is misbehaving and you want to isolate it
- You want to limit a bot's tool access without reconfiguring the workspace
- You are testing and want to toggle tools on and off

### Dashboard

Open the workspace, find the server in the list, and toggle the **Enabled** switch.

### CLI

```bash
# Disable a server
aerostack workspace server disable my-workspace github

# Re-enable it
aerostack workspace server enable my-workspace github
```

---

## Reorder Servers

Control the display order of servers in your workspace. The order affects how tools appear in the merged tool list.

Each server has a `display_order` value (0 to 9999, lower numbers first). Update it from the dashboard by dragging servers, or via the CLI:

```bash
aerostack workspace server reorder my-workspace github --order 0
aerostack workspace server reorder my-workspace stripe --order 1
aerostack workspace server reorder my-workspace notion --order 2
```

---

## Remove a Server

Removing a server from a workspace removes the link only. The MCP server itself is not deleted -- you can re-add it later.

### Dashboard

Open the workspace, find the server, and click the **Remove** button.

### CLI

```bash
aerostack workspace server remove my-workspace github
```

  Removing a server immediately removes its tools from the workspace. Any in-progress tool calls to that server may fail.

---

## Test Server Connectivity

Before relying on a server, verify that it is reachable and responding correctly.

### Dashboard

Open the workspace, find the server, and click **Test Connection**. The dashboard shows whether the server is reachable and lists the tools it exposes.

### CLI

```bash
aerostack workspace server test my-workspace github
```

```
Server: github
Status: OK
Tools:  5
  - create_issue
  - list_repos
  - search_code
  - get_pr
  - merge_pr
```

If the test fails, the output includes the error (for example, `HTTP 401: Unauthorized` if the server's API key is wrong or missing).

---

## Visibility Rules

Not every server can be added to every workspace:

| Server Visibility | Who Can Add It |
|-------------------|---------------|
| **Public** | Anyone |
| **Private** | Only the server owner |
| **Team** | The server owner and their active team members |

If you try to add a server you do not have access to, the dashboard shows an error and the CLI returns a `403` status.

---

## Limits

| Plan | Max Servers per Workspace |
|------|--------------------------|
| Free | 5 |
| Starter | 15 |
| Pro | 50 |
| Business | 200 |
| Enterprise | Unlimited |

When you reach the limit, you need to remove an existing server or upgrade your plan to add more.

---

## Instant Propagation

Changes to a workspace's tool configuration propagate immediately. There is no cache delay and no need to restart connected clients. The next `tools/list` or `tools/call` request will reflect the updated configuration.

This means you can:
- Add a new server and use its tools immediately
- Disable a misbehaving server and stop it from being called
- Rotate a secret and have it take effect on the next tool call