MCP Client Guide

Canonical source: docs/MCP_USER_GUIDE.md. This page is refreshed from the Finch repository when the website builds.

Model Context Protocol (MCP) enables Finch to use external tools from MCP servers without writing custom integrations. Finch is an MCP client; its existing OpenAI-compatible HTTP endpoint remains the interface for applications that drive Finch as a model.

What is MCP?
Quick Start
Installing MCP Servers
Configuration
Using MCP Tools
REPL Commands
Popular MCP Servers
Troubleshooting

What is MCP?

Model Context Protocol is an open standard created by Anthropic for connecting AI assistants to external data sources and tools. MCP servers are small programs that expose tools via a JSON-RPC interface.

Benefits:

✅ Extensible - Add new capabilities without modifying Finch
✅ Configured transports - Finch connects to the MCP servers you configure over stdio; Streamable HTTP is not implemented, and legacy SSE configuration is rejected (src/tools/mcp/)
✅ Isolated - Each configured server runs as a separate process
✅ Simple - Configure via TOML, use via natural language

Examples of what you can do:

Read/write files on your computer (filesystem server)
Create GitHub issues and PRs (github server)
Query databases (postgres, sqlite servers)
Access Google Drive documents (gdrive server)
Send Slack messages (slack server)
And hundreds more…

Quick Start

1. Install a simple MCP server (filesystem example):

npm install -g @modelcontextprotocol/server-filesystem

2. Add to your config (~/.finch/config.toml):

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
transport = "stdio"
enabled = true

3. Start Finch:

finch

4. Verify connection:

> /mcp list
📡 Connected MCP Servers:
  • filesystem

5. Use the tools:

> List all files in /tmp using the filesystem server

Finch will automatically include mcp_filesystem_list_directory in the tools available to its model.

Installing MCP Servers

Most MCP servers are distributed via npm (Node Package Manager). You need Node.js installed first.

Install Node.js (if needed)

macOS:

brew install node

Linux:

# Ubuntu/Debian
sudo apt install nodejs npm

# Fedora
sudo dnf install nodejs npm

Windows: Download from nodejs.org

Install MCP Servers Globally

# Install a server globally (recommended)
npm install -g @modelcontextprotocol/server-filesystem

# Verify installation
which npx  # Should show /usr/local/bin/npx or similar

Note: Global installation (-g) means you can use the server from anywhere.

Configuration

MCP servers are configured in ~/.finch/config.toml under the [mcp_servers] section.

Basic Configuration

[mcp_servers.<server_name>]
command = "npx"                    # Command to run
args = ["-y", "<package_name>"]    # Arguments to command
transport = "stdio"                # Communication method (stdio only for now)
enabled = true                     # Whether to connect on startup
env = { }                          # Environment variables (optional)
timeout_secs = 300                 # Per-request timeout (optional; default 300)

Configuration Fields

Field	Required	Description	Example
`command`	Yes	Executable to run	`"npx"`, `"node"`, `"/path/to/binary"`
`args`	Yes	Command arguments	`["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]`
`transport`	Yes	Communication protocol	`"stdio"` (only option currently)
`enabled`	Yes	Connect on startup	`true` or `false`
`env`	No	Environment variables	`{ API_KEY = "$MY_API_KEY" }`
`timeout_secs`	No	Maximum seconds for initialize, discovery, or a tool call	`300`

Example: Multiple Servers

# Filesystem access (read-only)
[mcp_servers.filesystem_readonly]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
transport = "stdio"
enabled = true

# GitHub integration
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
transport = "stdio"
enabled = true
env = { GITHUB_TOKEN = "$GITHUB_TOKEN" }  # Reads from environment

# Database access
[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
transport = "stdio"
enabled = false  # Disabled by default
env = { DATABASE_URL = "postgresql://localhost:5432/mydb" }

Environment Variables

Environment values can be:

Literal values: { API_KEY = "abc123" }
Exact references: { API_KEY = "$MY_API_KEY" } or { API_KEY = "${MY_API_KEY}" }

Finch resolves exact references from its own environment without invoking a shell. A missing referenced variable prevents that server from connecting and is reported in the logs. Interpolation inside a larger string is deliberately not performed.

Security Note: Store sensitive tokens in your shell environment (e.g., ~/.zshrc), not in the config file:

# In ~/.zshrc or ~/.bashrc
export GITHUB_TOKEN="ghp_your_token_here"
export DATABASE_URL="postgresql://..."

Then reference in config:

[mcp_servers.github]
env = { GITHUB_TOKEN = "$GITHUB_TOKEN" }

Using MCP Tools

Once configured, MCP tools work just like built-in tools. You don’t need to know the exact tool names - just ask naturally!

Natural Language Examples

Filesystem:

> What files are in my Downloads folder?
> Read the contents of README.md
> Show me all Python files in the current directory

GitHub (if github server configured):

> Create an issue in my repo titled "Fix authentication bug"
> List all open pull requests in the anthropics/claude repository
> Show me recent commits on the main branch

Database (if postgres server configured):

> Query my database for all users created in the last week
> Show me the schema of the users table
> Count how many orders exist in the database

Direct Tool Invocation

If you know the exact tool name, you can use it directly:

> Use mcp_filesystem_read_file to read /etc/hosts
> Use mcp_github_create_issue with title "Bug" and body "Description"

Tool Name Format

MCP tools are automatically prefixed to avoid conflicts:

mcp_<server>_<tool>

Examples:
  mcp_filesystem_read_file          (from "filesystem" server)
  mcp_github_create_issue           (from "github" server)
  mcp_postgres_query                (from "postgres" server)

REPL Commands

Finch provides /mcp commands to manage MCP servers at runtime.

/mcp list

List all connected MCP servers:

> /mcp list
📡 Connected MCP Servers:
  • filesystem
  • github
  • postgres

Shows which servers are currently connected and available.

/mcp tools [server]

List all tools (from all servers):

> /mcp tools
🔧 All MCP Tools:
  • filesystem_read_file
    Read contents of a file
  • filesystem_list_directory
    List files in a directory
  • github_create_issue
    Create a new issue in a repository
  ...

List tools from specific server:

> /mcp tools filesystem
🔧 MCP Tools from 'filesystem' server:
  • filesystem_read_file
    Read contents of a file
  • filesystem_list_directory
    List files in a directory
  • filesystem_write_file
    Write contents to a file

/mcp refresh

Refresh tool list from all servers:

> /mcp refresh
Refreshing MCP tools...
✓ Refreshed MCP tools (24 tools available)

Use this if you update an MCP server or if tools aren’t appearing correctly.

/mcp reload

Reconnect to all configured servers:

> /mcp reload
Reconnecting to configured MCP servers...
✓ Connected to 2 MCP server(s) with 17 tool(s)

Disabled servers remain disabled. A failed server is logged while other configured servers continue connecting.

Popular MCP Servers

Official Anthropic Servers

Filesystem

Access local files and directories

npm install -g @modelcontextprotocol/server-filesystem

Config:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
transport = "stdio"
enabled = true

Tools:

read_file - Read file contents
list_directory - List files in directory
write_file - Write to file
move_file - Move/rename files
create_directory - Create directory
search_files - Search for files

Security: Restricts access to the specified directory only.

GitHub

Interact with GitHub repositories

npm install -g @modelcontextprotocol/server-github

Config:

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
transport = "stdio"
enabled = true
env = { GITHUB_TOKEN = "$GITHUB_TOKEN" }

Setup GitHub Token:

Go to https://github.com/settings/tokens
Generate new token (classic)
Select scopes: repo, read:org
Copy token
Add to shell: export GITHUB_TOKEN="ghp_..."

Tools:

create_issue - Create new issue
create_pull_request - Create PR
list_issues - List issues
search_repositories - Search repos
get_file_contents - Read file from repo

PostgreSQL

Query PostgreSQL databases

npm install -g @modelcontextprotocol/server-postgres

Config:

[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
transport = "stdio"
enabled = true
env = { DATABASE_URL = "$DATABASE_URL" }

Tools:

query - Execute SQL query
list_tables - Show all tables
describe_table - Show table schema

Community Servers

Google Drive

Access Google Drive files

npm install -g @modelcontextprotocol/server-gdrive

Requires OAuth setup - see server documentation.

Slack

Send messages and interact with Slack

npm install -g @modelcontextprotocol/server-slack

Requires Slack app token - see server documentation.

SQLite

Query SQLite databases

npm install -g @modelcontextprotocol/server-sqlite

Brave Search

Web search via Brave API

npm install -g @modelcontextprotocol/server-brave-search

Finding More Servers

Official list: https://github.com/modelcontextprotocol/servers

npm search: npm search modelcontextprotocol

Troubleshooting

MCP servers not connecting

Symptom: /mcp list shows no servers, or specific server missing

Causes & Solutions:

Server not installed:

# Check if package is installed
npm list -g @modelcontextprotocol/server-filesystem

# If not found, install it
npm install -g @modelcontextprotocol/server-filesystem

Config error:
- Check ~/.finch/config.toml syntax
- Ensure enabled = true
- Verify command path: which npx
- Check args are valid
Permission issues:
- Check file permissions on config
- Verify MCP server has execute permissions
- Check directory access (for filesystem server)

Environment variable not set:

# Verify environment variable exists
echo $GITHUB_TOKEN

# If empty, set it in ~/.zshrc or ~/.bashrc
export GITHUB_TOKEN="ghp_..."

# Reload shell
source ~/.zshrc

Check Finch logs:

# Look for MCP-related errors
finch 2>&1 | grep -i mcp

Tools not appearing

Symptom: /mcp list shows server, but /mcp tools shows no tools

Solutions:

Refresh tools:
```
> /mcp refresh
```
Restart Finch:
Terminal window
```
# Exit
> /quit

# Start again
finch
```
Check server compatibility:
- Ensure server implements MCP tools correctly
- Test server directly: npx -y @modelcontextprotocol/server-filesystem /tmp
- Check for JSON-RPC responses

Tools not executing

Symptom: AI tries to use tool but gets error

Causes & Solutions:

Tool permission denied:
- Check if tool confirmation dialog appeared
- Approve the tool execution
- Or enable auto-approve: config.features.auto_approve_tools = true
Invalid parameters:
- Tool may have specific parameter requirements
- Check tool schema: /mcp tools <server>
- Verify AI is passing correct JSON structure
Server crashed:
- Restart Finch to reconnect
- Check if server command still works: which npx
- Look for stderr output in terminal

“MCP plugin system not configured”

Symptom: Commands show this message

Solution: Add at least one MCP server to ~/.finch/config.toml:

[mcp_servers.example]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
transport = "stdio"
enabled = true

Node.js / npm not found

Symptom: command not found: npx or similar

Solution:

# macOS
brew install node

# Linux (Ubuntu/Debian)
sudo apt install nodejs npm

# Verify
which node
which npx

Slow tool execution

Causes:

MCP server doing expensive operation (database query, API call)
Network latency (for remote resources)
Large file operations

Normal behavior - MCP tools run in separate processes, so some latency is expected.

Security Best Practices

Limit filesystem access:

# ❌ DON'T give access to entire filesystem
args = ["-y", "@modelcontextprotocol/server-filesystem", "/"]

# ✅ DO restrict to specific directories
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]

Use environment variables for secrets:

# ❌ DON'T put secrets in config
env = { API_KEY = "abc123secretkey" }

# ✅ DO use environment variables
env = { API_KEY = "$MY_API_KEY" }

Disable unused servers:

[mcp_servers.rarely_used]
enabled = false  # Won't connect on startup

Review tool permissions:
- Don’t auto-approve all tools blindly
- Review what each tool does before first use
- Use patterns for repetitive safe operations only

Keep servers updated:

npm update -g @modelcontextprotocol/server-filesystem

Advanced Configuration

Custom Server Paths

If you built an MCP server yourself or it’s not an npm package:

[mcp_servers.custom]
command = "/usr/local/bin/my-mcp-server"
args = ["--port", "9000", "--data-dir", "/var/data"]
transport = "stdio"
enabled = true

Multiple Instances

Run multiple instances of the same server with different configs:

[mcp_servers.projects_workspace]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
transport = "stdio"
enabled = true

[mcp_servers.documents_workspace]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
transport = "stdio"
enabled = true

Debugging MCP Communication

Enable debug logging to see JSON-RPC messages:

[features]
debug_logging = true

Then check logs for MCP-related messages:

finch 2>&1 | grep -i "mcp\|jsonrpc"

Getting Help

Issues: https://github.com/darwin-finch/finch/issues

Questions: Create a GitHub discussion or issue

Contributing: PRs welcome for new MCP integrations or documentation improvements!

Last Updated: 2026-08-21 Finch Version: 0.7.31+ Newest MCP Protocol Version: 2026-07-28 (with negotiation for earlier revisions)

MCP Client Guide

Table of Contents

What is MCP?

Quick Start

Installing MCP Servers

Install Node.js (if needed)

Install MCP Servers Globally

Configuration

Basic Configuration

Configuration Fields

Example: Multiple Servers

Environment Variables

Using MCP Tools

Natural Language Examples

Direct Tool Invocation

Tool Name Format

REPL Commands

/mcp list

/mcp tools [server]

/mcp refresh

/mcp reload

Popular MCP Servers

Official Anthropic Servers

Filesystem

GitHub

PostgreSQL

Community Servers

Google Drive

Slack

SQLite

Brave Search

Finding More Servers

Troubleshooting

MCP servers not connecting

Tools not appearing

Tools not executing

“MCP plugin system not configured”

Node.js / npm not found

Slow tool execution

Security Best Practices

Advanced Configuration

Custom Server Paths

Multiple Instances

Debugging MCP Communication

Further Reading

Getting Help