Mcp Setup

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

assistant/CLAUDE.md

assistant/src/approvals/CLAUDE.md

assistant/src/notifications/CLAUDE.md

assistant/src/runtime/CLAUDE.md

gateway/CLAUDE.md

Audit 0.4.1 · source sha 19bc86343b63 · 14 Oct 2026Report an issue or request a re-scan

• Publishervellum-ai GitHub organizationOwner of the repository this skill is read from
• Source foldervellum-ai/vellum-assistant/skills/mcp-setupThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict19bc86343b63A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Add, authenticate, list, and remove MCP (Model Context Protocol) servers — connect any external tool or service that publishes an MCP endpoint to the assistant

---
name: mcp-setup
description: Add, authenticate, list, and remove MCP (Model Context Protocol) servers — connect any external tool or service that publishes an MCP endpoint to the assistant
compatibility: "Works on both the Vellum desktop app (local daemon) and the Vellum web app (platform-hosted). Auth flow differs by environment."
metadata:
  emoji: "🔌"
  vellum:
    category: "integrations"
    display-name: "MCP Setup"
---

Configure MCP servers to give the assistant access to any external tool or service that publishes an MCP endpoint.

**DO NOT** run exploratory commands. Do not check available CLI commands, search for bun/npx/node, or investigate transport types. Follow the steps below exactly and stop when done. (Looking up a service's MCP endpoint URL in its own documentation is allowed when the service is not in the recipe table, per Step 3.)

## When to Use

USE THIS SKILL WHEN:

- User asks to connect any external tool or service via MCP
- User asks "what MCP servers / integrations do I have?"
- An MCP tool returns an auth error → run `assistant mcp auth <name>`
- User wants to disconnect an integration

## Prefer Native OAuth Integration (check this first)

Many services have built-in OAuth integrations that are simpler and more reliable than MCP. Before setting up MCP, check whether the service already has a native OAuth provider:

```
assistant oauth providers list
```

If the service appears in that list, connect it natively instead of using MCP:

```
assistant oauth connect <provider>
```

**Only use MCP when:**

- The service is not in `assistant oauth providers list`
- The user explicitly asks to use MCP for a specific service
- The native OAuth integration fails or lacks features the user needs

## Step 1 — Detect your environment

**Before doing anything else**, determine which environment you are in.

Try `host_bash`:

```
echo "desktop ok"
```

- If it succeeds → you are on the **desktop app**. Use `host_bash` for all commands, including `auth` (opens a local browser).
- If it is unavailable → you are on the **web app** (or a cloud-hosted session). Use `bash` for all commands, including `auth` (the platform handles the browser redirect).

Both environments fully support MCP. The only difference is which tool runs the commands.

## Step 2 — Check the recipe table

**Check this table before doing anything else.** If the service is listed, run the command shown and do nothing else — no exploration, no checking available commands, no looking up documentation.

| Service         | Command                                                                                | After?                          |
| --------------- | -------------------------------------------------------------------------------------- | ------------------------------- |
| Context7 (docs) | `assistant mcp add context7 -t streamable-http -u https://mcp.context7.com/mcp -r low` | Done — no auth needed           |
| Linear          | `assistant mcp add linear -t streamable-http -u https://mcp.linear.app/mcp`            | Run `assistant mcp auth linear` |
| Figma           | `assistant mcp add figma -t streamable-http -u https://mcp.figma.com/mcp`              | Run `assistant mcp auth figma`  |

If the service is not in this table, go to Step 3.

## Step 3 — Unknown service

Find the MCP endpoint URL in the service's documentation, then run:

```
assistant mcp add <name> -t streamable-http -u <url>
```

Then run `assistant mcp list`. If it shows `! Needs authentication`, run `assistant mcp auth <name>`.

- On **desktop** → run via `host_bash` (opens the local browser).
- On **web app** → run via `bash` (the platform handles the browser redirect).

---

## Reference: All Commands

Run `list`, `add`, `remove`, and `reload` via `bash` on both environments. Run `auth` via `host_bash` on desktop, or via `bash` on the web app.

### List servers

```
assistant mcp list
assistant mcp list --json   # machine-readable output
```

Shows each server's connection status, transport, and URL/command. Status indicators:

- `✓` Connected
- `✗` Error
- `!` Needs authentication

### Add a server

```
assistant mcp add <name> -t <transport> -u <url>
```

Transport types:

- `streamable-http` — most modern remote servers (use this by default)
- `sse` — legacy remote servers
- `stdio` — local process: use `-c <command>` and `-a <args...>` instead of `-u`

Examples:

```
assistant mcp add linear -t streamable-http -u https://mcp.linear.app/mcp
assistant mcp add context7 -t streamable-http -u https://mcp.context7.com/mcp
assistant mcp add local-db -t stdio -c npx -a -y @my/mcp-server
```

### Authenticate (OAuth)

```
assistant mcp auth <name>
```

- On **desktop** → run via `host_bash` (opens the user's local browser for OAuth login).
- On **web app** → run via `bash` (the platform handles the browser redirect and saves tokens).

Tokens are saved automatically. Use when:

- `assistant mcp list` shows `! Needs authentication`
- An MCP tool call fails with an auth/token error
- Setting up a new OAuth-protected server for the first time

### Remove a server

```
assistant mcp remove <name>
```

Removes config and cleans up stored OAuth credentials.

### Reload

```
assistant mcp reload
```

Manually signals the assistant to reconnect all MCP servers from disk. Normally not needed — the assistant detects changes automatically after `add`, `remove`, and `auth`. Use this only if a server's tools aren't appearing after ~10 seconds.

## Advanced Configuration

`mcp add` covers the common cases. For stdio environment variables, edit `$VELLUM_WORKSPACE_DIR/mcp.json` under `mcpServers.<name>.env`. Auth headers for remote servers go through `assistant mcp add -H` or the settings UI, not `mcp.json`.

## SKILL COMPLETE WHEN

Match the completion condition to the task:

- **Add / authenticate:** the server appears in `assistant mcp list` with status `✓ Connected` and the user confirms its tools are available in the conversation.
- **Lis

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/vellum-ai/vellum-assistant
git -C vellum-assistant checkout 19bc86343b63

Works in

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source 19bc86343b63

Questions about Mcp Setup

• github.com/vellum-ai/vellum-assistant/tree/main/skills/mcp-setup — the audited source at commit 19bc86343b63 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology