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

# Adding MCP servers

> Expand pflow capabilities with external tools

MCP (Model Context Protocol) servers let you add external tools to pflow. Once added, your AI agent can use these tools in workflows - GitHub, Slack, databases, and more.

pflow supports both **local (stdio)** and **remote (HTTP)** MCP servers.

## Adding a server

### From a config file

If you have an MCP config file (JSON format):

```bash theme={null}
pflow mcp add ./github.mcp.json
```

Config file format:

```json theme={null}
{
  "github": {
    "command": "npx",
    "args": ["-y", "@github/mcp-server"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
    }
  }
}
```

### From JSON directly

For quick setup, pass JSON directly:

```bash theme={null}
# Local stdio server
pflow mcp add '{"github": {"command": "npx", "args": ["-y", "@github/mcp-server"]}}'

# Remote HTTP server
pflow mcp add '{"slack": {"type": "http", "url": "https://mcp.example.com/slack"}}'
```

### Multiple servers at once

Add multiple servers from separate files:

```bash theme={null}
pflow mcp add ./github.mcp.json ./slack.mcp.json ./notion.mcp.json
```

## Tools are auto-discovered

You don't need to manually sync after adding a server. When your agent runs a workflow, pflow automatically discovers tools from any new or changed servers.

<Tip>
  If you want to test the connection immediately after adding a server, run `pflow mcp sync <server-name>` to force discovery.
</Tip>

## Managing servers

### List configured servers

```bash theme={null}
pflow mcp list
```

### View available tools

See all tools from a specific server:

```bash theme={null}
pflow mcp list github
```

Or list all tools from all servers:

```bash theme={null}
pflow mcp list
```

### Get tool details

See detailed information about a specific tool:

```bash theme={null}
pflow mcp describe mcp-github-create-issue
```

### Remove a server

```bash theme={null}
pflow mcp remove github
```

## Configuration file location

pflow stores MCP server configurations in:

```
~/.pflow/mcp-servers.json
```

You can edit this file directly instead of using `pflow mcp add`. After manual edits, run `pflow mcp sync <server-name>` or `pflow mcp sync --all` to register the changes.

The file uses the [standard MCP configuration format](https://modelcontextprotocol.io/docs/develop/connect-local-servers) used by Claude Desktop, VS Code, and other MCP clients.

## Server configuration format

### Local (stdio) servers

Local servers run as subprocesses on your machine. The `type` field is optional and defaults to `"stdio"`:

```json theme={null}
{
  "server-name": {
    "command": "npx",
    "args": ["-y", "@namespace/mcp-server"],
    "env": {
      "API_KEY": "your-key"
    }
  }
}
```

| Field     | Required | Description                                        |
| --------- | -------- | -------------------------------------------------- |
| `command` | Yes      | The command to run (e.g., `npx`, `python`, `node`) |
| `args`    | No       | Command arguments                                  |
| `env`     | No       | Environment variables passed to the server         |

### Remote (HTTP) servers

Remote servers connect over HTTP/SSE. The `type` field is **required** for HTTP servers:

```json theme={null}
{
  "server-name": {
    "type": "http",
    "url": "https://mcp.example.com/server",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}"
    }
  }
}
```

| Field     | Required | Description                         |
| --------- | -------- | ----------------------------------- |
| `type`    | Yes      | Must be `"http"` for remote servers |
| `url`     | Yes      | The server URL (SSE endpoint)       |
| `headers` | No       | HTTP headers for authentication     |

### Environment variable expansion

Use `${VAR}` syntax to reference environment variables in your config:

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

Variables are resolved from two sources (in order of precedence):

1. **System environment** - `export GITHUB_TOKEN="your-token"`
2. **pflow settings** - `pflow settings set-env GITHUB_TOKEN "your-token"`

Use `${VAR:-default}` for fallback values:

```json theme={null}
{
  "url": "${API_URL:-https://api.example.com}"
}
```

Variables are expanded at runtime when the server starts, not when the config is saved.

## Using MCP tools in workflows

Once added, MCP tools become pflow nodes that your agent can use:

```bash theme={null}
# Discover relevant tools
pflow mcp find "create github issues"

# See tool parameters
pflow mcp describe mcp-github-create_issue
```

See [MCP nodes](/reference/nodes/mcp) for how these nodes work in workflows - naming convention, parameters, output format, and examples.

<Tip>
  If you're repeatedly calling the same API using the [http node](/reference/nodes/http), consider having your agent create an MCP server for it. This turns one-off HTTP requests into reusable, discoverable tools.
</Tip>

## Common MCP servers

Here are some popular MCP servers. Save any of these as a `.json` file and add with `pflow mcp add ./filename.json`:

### GitHub

```json theme={null}
{
  "github": {
    "command": "npx",
    "args": ["-y", "@github/mcp-server"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}
```

See [github/github-mcp-server](https://github.com/github/github-mcp-server) for full documentation.

### Filesystem

<Note>
  For basic file operations, pflow includes built-in [file nodes](/reference/nodes/file) - no MCP server needed. The filesystem MCP server is useful for advanced operations or stricter directory sandboxing. If you do use it, consider disabling the built-in file nodes to avoid confusion: `pflow settings deny "pflow.nodes.file.*"`.
</Note>

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

### Brave Search

```json theme={null}
{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@brave/brave-search-mcp-server"],
    "env": {
      "BRAVE_API_KEY": "${BRAVE_API_KEY}"
    }
  }
}
```

See [Brave Search API](https://brave.com/search/api/) for API key setup (free tier: 2,000 queries/month).

<Note>
  Find more MCP servers at the [Official MCP Registry](https://registry.modelcontextprotocol.io) or the community-curated [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) list.
</Note>

## Troubleshooting

<Accordion title="Server not appearing in list">
  1. Check your JSON syntax is valid
  2. Make sure the config file path is correct
  3. Run `pflow mcp servers` to see configured servers
</Accordion>

<Accordion title="Tools not discovered">
  1. Check the server is running correctly: `pflow mcp sync <server-name>`
  2. Verify credentials/environment variables are set
  3. Check the server logs for errors
</Accordion>

<Accordion title="Tool execution fails">
  1. Run `pflow mcp describe <tool-name>` to see required parameters
  2. Check that required environment variables are set in the server config
  3. Verify the server has access to required resources (network, files, etc.)
</Accordion>