> ## Documentation Index
> Fetch the complete documentation index at: https://slackhive.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Servers

> Connect your agents to databases, APIs, and external services using the Model Context Protocol.

## What is MCP?

**MCP (Model Context Protocol)** is a standard that lets AI agents connect to external tools and data sources. Think of MCP servers as plugins for your agents - they give agents the ability to actually *do* things beyond just having a conversation.

Without MCP, an agent can only talk. With MCP, an agent can:

* Query your database and return real results
* Read files from a repository
* Create GitHub issues
* Fetch data from any internal API
* Run custom scripts

An MCP server is a small program that exposes a set of **tools**. When an agent needs to do something - like run a SQL query - it calls the appropriate MCP tool, gets back the result, and incorporates it into its response.

<Note>
  You don't need to build MCP servers from scratch. There are [many open-source MCP servers](https://github.com/modelcontextprotocol/servers) for common tools. SlackHive also supports **inline TypeScript MCPs** - you can paste code directly into the UI without deploying anything.
</Note>

## How SlackHive manages MCP

SlackHive manages MCP servers at the **platform level**. You add a server once to the global catalog, then assign it to any number of agents.

When an agent starts, SlackHive launches all its assigned MCP servers and keeps them running. There's no per-message startup overhead - once the agent is live, its tools are always ready.

Tool names follow the pattern `mcp__{serverName}__{toolName}`. For example, a server named `redshift` with a `query` tool is called as `mcp__redshift__query`.

## The catalog - Official vs Community

The platform catalog surfaces two badges:

| Badge         | Meaning                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------- |
| **Official**  | Curated template maintained by SlackHive - tested and kept in sync with upstream MCP packages |
| **Community** | Server you or a teammate added - not vetted                                                   |

Browse the catalog, assign an Official template, fill in env vars, and you're done.

## Adding a server to the catalog

<Steps>
  <Step title="Open MCP Servers">
    Sidebar → **MCP Catalog**.
  </Step>

  <Step title="Pick a starting point">
    Three options:

    * **Browse Library** - pick from the curated server library
    * **Import from Claude Code CLI** - add MCPs already registered in your local `claude` CLI when that backend is available
    * **Custom Server** - paste a Cursor / Claude Desktop / VS Code config, or fill in fields
  </Step>

  <Step title="Fill in the blanks">
    In **Custom Server** the default view is a JSON textarea that accepts the standard `{ "mcpServers": { ... } }` shape used by Cursor, Claude Desktop, and VS Code. Use `${env:NAME}` for secrets - see [Paste JSON from other tools](#paste-json-from-other-tools) below. Prefer granular fields? Switch to the **Form** tab.
  </Step>

  <Step title="Probe the server">
    Click **Test Connection**. SlackHive runs a real MCP handshake - `initialize`, `tools/list` - against the server. You see the list of tools it exposes. If the probe fails, the error is shown inline with the tool stderr.
  </Step>

  <Step title="Save">
    Saves to the catalog. The server is now available for agent assignment.
  </Step>
</Steps>

## Import from Claude Code CLI

If you've already set up MCPs via the `claude` CLI (`claude mcp add ...`), SlackHive can import them one-click.

1. In **MCP Catalog**, click **Import from Claude Code**
2. You see the full list from `claude mcp list`
3. Click **Import** on any server - it's added to the catalog with a **CLI** badge
4. Adjust the env and config as needed

This is the fastest path for teams who already manage MCPs through `claude` locally.

## Transport types

There are four ways to run an MCP server:

| Transport         | Use case                                                              |
| ----------------- | --------------------------------------------------------------------- |
| `stdio`           | A local process (Node.js script, Python script, binary) - most common |
| `sse`             | A remote server accessible via HTTP server-sent events                |
| `http`            | A remote server accessible via HTTP                                   |
| TypeScript inline | Paste TypeScript source directly - no deployment needed               |

## Configuration examples

These examples use the standard Cursor / Claude Desktop / VS Code shape - paste them directly into the JSON textarea in **Custom Server**.

### Redshift / Data Warehouse

Give your data analyst agent the ability to run real SQL queries:

```json theme={null}
{
  "mcpServers": {
    "redshift": {
      "command": "node",
      "args": ["/path/to/redshift-mcp/dist/index.js"],
      "env": {
        "DATABASE_URL": "${env:REDSHIFT_DATABASE_URL}"
      }
    }
  }
}
```

<Tip>
  `${env:REDSHIFT_DATABASE_URL}` pulls the secret from the encrypted env store at spawn time instead of embedding it in the config. See [Keeping secrets safe](#keeping-secrets-safe) below.
</Tip>

### Filesystem Access

Give an agent read access to files in a directory - useful for code review or documentation agents:

```json theme={null}
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/repo"]
    }
  }
}
```

The agent can then use `mcp__filesystem__read_file`, `mcp__filesystem__list_directory`, etc.

### Remote API (SSE)

Connect to a remote MCP server over the network:

```json theme={null}
{
  "mcpServers": {
    "analytics-api": {
      "url": "https://mcp.internal.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${env:ANALYTICS_TOKEN}"
      }
    }
  }
}
```

The `Bearer ` prefix stays literal; `${env:ANALYTICS_TOKEN}` is resolved at spawn time and the runner assembles the final header value.

## Paste JSON from other tools

The **Custom Server** editor opens on a JSON textarea by default. It accepts the same `{ "mcpServers": { ... } }` shape used by Cursor, Claude Desktop, and VS Code - so any config you already have elsewhere can be pasted verbatim.

Two shapes are accepted:

```json theme={null}
{
  "mcpServers": {
    "elasticsearch": {
      "command": "npx",
      "args": ["-y", "@elastic/mcp-server-elasticsearch"],
      "env": {
        "ES_URL": "${env:ES_URL}",
        "ES_API_KEY": "${env:ES_API_KEY}"
      }
    }
  }
}
```

Or a bare server object (name comes from the **Name** field):

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "@elastic/mcp-server-elasticsearch"],
  "env": { "ES_URL": "${env:ES_URL}" }
}
```

**`${env:NAME}` substitution.** Any value matching `${env:NAME}` is mapped to the SlackHive encrypted env store. At spawn time the runner resolves the reference and injects the secret into the subprocess environment - the raw value never lands in the config row. Prefixes are preserved, so `"Authorization": "Bearer ${env:GH_TOKEN}"` resolves to `Bearer <secret>`.

**Missing env vars.** If your JSON references an env var that doesn't exist in the store yet, a chip appears under the textarea. Click it to set the value inline without leaving the editor.

**Editing existing servers.** Reopening a saved server re-serializes its config back to the JSON shape. Inline secrets come back as `"********"` - leave them alone to preserve the stored value, or replace with a real value or `${env:NAME}` ref to change it.

**Form mode.** A **Form** tab next to **JSON** exposes the granular fields for users who prefer them. Toggling seeds the other view, so switching mid-edit doesn't lose work.

### Inline TypeScript

The most convenient option for internal tools: paste TypeScript source directly into the UI. SlackHive writes it to disk and runs it - no separate deployment needed.

Select **TypeScript inline script** as the transport type, then paste your implementation:

```typescript theme={null}
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "my-tool", version: "1.0.0" });

server.tool(
  "lookup_customer",
  { customer_id: z.string() },
  async ({ customer_id }) => ({
    content: [{ type: "text", text: `Customer ${customer_id}: Acme Corp, Plan: Pro` }],
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);
```

This is ideal for simple tools you want to prototype quickly, or for internal utilities you don't want to expose as file paths.

## Assigning servers to agents

Once a server is in the catalog, you can assign it to agents:

* Open the agent
* Go to the **Tools** tab
* Assign one or more MCP servers from the catalog

An agent can have any number of MCP servers assigned. All tools from all assigned servers become available to the agent.

### Who can assign which MCP

The catalog is workspace-wide — every authenticated user sees every MCP — but assignment is gated by ownership:

| Role                   | What they can assign                              |
| ---------------------- | ------------------------------------------------- |
| **Editor**             | Only MCPs they created (`createdBy = themselves`) |
| **Admin / Superadmin** | Any MCP regardless of owner                       |

This applies on the per-agent Tools tab. MCPs you can't assign are disabled, and SlackHive rejects unauthorized assignments. The intent is that an MCP holding production credentials (a private database PAT, a paid API key) can only be wired into agents by the person who configured it — or an admin who has explicit authority.

To hand off ownership, the current owner deletes their MCP and the new owner re-creates it, or an admin updates the `created_by` column directly.

## Keeping secrets safe

Never paste database credentials, API keys, or passwords directly into MCP config `env` fields. Use the **encrypted env store** instead.

The env store encrypts secrets at rest using AES-256. Values are never returned by the API or shown in the browser - only the key names are visible.

<Steps>
  <Step title="Add your secret to the store">
    1. Go to **Settings → Env Vars** in the sidebar
    2. Click **Add Variable**
    3. Enter a name (e.g. `REDSHIFT_DATABASE_URL`) and the secret value
    4. Click **Save** - the value is encrypted immediately
  </Step>

  <Step title="Reference it in your MCP config">
    Use `${env:NAME}` inside any `env` value (or HTTP `headers` value) to pull the secret from the store:

    ```json theme={null}
    {
      "mcpServers": {
        "redshift": {
          "command": "node",
          "args": ["/path/to/redshift-mcp/dist/index.js"],
          "env": {
            "DATABASE_URL": "${env:REDSHIFT_DATABASE_URL}"
          }
        }
      }
    }
    ```

    When the agent starts, the runner decrypts `REDSHIFT_DATABASE_URL` from the store and injects it as `DATABASE_URL` into the MCP process environment.
  </Step>
</Steps>

The raw secret never appears in API responses, browser dev tools, or log files. Reopening the editor later shows `"********"` in place of any inline secret values you did paste literally - leaving them untouched preserves the stored value.

## Testing a server

From **MCP Catalog**, any user with an **editor role or above** can click the **Test** button next to any server — regardless of who created it. SlackHive runs a full MCP handshake:

1. Launches the server process (or connects to the remote URL)
2. Sends `initialize`
3. Sends `tools/list`
4. Displays the discovered tools inline

If the probe fails, you see the error with stderr. If a server fails to start at runtime, the agent still runs - the failure is logged, and the agent continues without that server's tools. Check the agent's **Logs** tab for details.

## OAuth MCPs

Some servers (Figma, Linear, remote Anthropic MCPs) require OAuth. SlackHive supports three OAuth flows:

1. **Dynamic client registration** - click **Connect** in the catalog, complete the OAuth dance
2. **Paste token** - for providers that block dynamic registration
3. **Claude Code CLI import** - if the MCP is already authorized in your local `claude` install

See [OAuth MCPs](/configuration/mcp-oauth) for the full flow.

## Next steps

<CardGroup cols={2}>
  <Card title="Agent Tools & Permissions" icon="shield" href="/agents/tools">
    Control exactly which MCP tools each agent can use.
  </Card>

  <Card title="OAuth MCPs" icon="key" href="/configuration/mcp-oauth">
    Connect servers that require OAuth authentication.
  </Card>
</CardGroup>