MCP Servers

MCP Servers

Clipboard Recast supports the Model Context Protocol (MCP), an open standard that allows AI applications to connect with external tools, data sources, and services. With MCP support, you can extend Clipboard Recast’s capabilities far beyond built-in transformations.

Important: Installation Required

MCP servers are external programs that must be installed separately on your Mac before you can use them in Clipboard Recast. The app provides templates to help configure connections, but you need to install the MCP server yourself first.

Installation Methods:

• npm - npm install -g @modelcontextprotocol/server-filesystem (requires Node.js)
• npx - Run without installing: npx -y @modelcontextprotocol/server-filesystem
• uvx - For Python-based servers: uvx mcp-server-sqlite
• Docker - Run containerized servers
• Build from source - Clone and build server repositories

Quick Start (npm):

1. Install Node.js from nodejs.org (if not already installed)
2. Install the MCP server: npm install -g @modelcontextprotocol/server-filesystem
3. Add the server in Clipboard Recast using a template
4. Connect and start using the tools

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how AI applications communicate with external tools and services. Think of MCP servers as plugins that give Clipboard Recast new abilities:

• File Operations: Read, write, search, and manage files on your system
• Database Access: Query PostgreSQL, SQLite, or other databases
• API Integrations: Connect to GitHub, Slack, Linear, and other services
• Web Browsing: Fetch and analyze web content
• System Tools: Execute commands, manage processes, and more

Why Use MCP?

Extend Your Workflows

Without MCP, Clipboard Recast workflows are limited to built-in actions. With MCP, you can:

• Save AI-generated code directly to your project files
• Create GitHub issues from error messages
• Post summaries to Slack channels
• Query databases and transform the results
• Search your codebase and analyze the findings

Unified Interface

Instead of switching between multiple tools, MCP brings external capabilities directly into your clipboard workflows. Copy an error, and your workflow can automatically search your codebase for related files, check recent commits, and suggest fixes.

Community Ecosystem

MCP has a growing ecosystem of pre-built servers for popular services. You can use existing servers or create custom ones for your specific needs.

Accessing MCP Servers

Open the MCP Servers window:

• Click menu bar icon → MCP Servers…

The MCP Servers Window

The MCP Servers window has two panels:

Left Panel: Server List

Shows all configured MCP servers with:

• Status Indicator: Green (connected), Yellow (connecting), Red (error), Gray (disconnected)
• Server Name: The name you gave the server
• Connection Status: Current status text

Buttons:

• Add…: Add a new MCP server
• Remove: Delete selected server
• Connect/Disconnect: Toggle server connection

Right Panel: Available Tools

When connected, shows tools provided by the selected server:

• Tool: Name of the tool
• Description: What the tool does

Tips for viewing tool details:

• Hover over any cell to see the full text in a tooltip
• Double-click a row to see complete tool information including parameters

Adding an MCP Server

Step 1: Click “Add…”

Opens the Add MCP Server dialog.

Step 2: Choose a Template (Optional)

Templates provide pre-filled configuration for popular MCP servers. Important: Templates only configure the connection settings - you must install the MCP server package separately before it will work.

Template	Description	Install Command
Filesystem	Read, write, and search files	npm install -g @modelcontextprotocol/server-filesystem
GitHub	Manage repositories, issues, PRs	npm install -g @modelcontextprotocol/server-github
Slack	Send messages and manage channels	npm install -g @modelcontextprotocol/server-slack
PostgreSQL	Query PostgreSQL databases	npm install -g @modelcontextprotocol/server-postgres
SQLite	Query SQLite databases	npm install -g @modelcontextprotocol/server-sqlite
Puppeteer	Browser automation	npm install -g @modelcontextprotocol/server-puppeteer
Brave Search	Web search	npm install -g @modelcontextprotocol/server-brave-search
Google Maps	Location and mapping	npm install -g @modelcontextprotocol/server-google-maps
Memory	Persistent key-value storage	npm install -g @modelcontextprotocol/server-memory
Sequential Thinking	Enhanced reasoning	npm install -g @modelcontextprotocol/server-sequential-thinking
Fetch	HTTP requests	npm install -g @modelcontextprotocol/server-fetch
Everything	Windows file search	npm install -g @modelcontextprotocol/server-everything

Or choose “Custom Server” for manual configuration.

Prerequisites

Before using any MCP server, you need the appropriate runtime installed:

• For npm/npx servers: Node.js from nodejs.org
• For uvx/Python servers: Python 3 and uv (pip install uv)
• For Docker servers: Docker Desktop

Step 3: Configure Server Settings

Name: A descriptive name for the server

• Example: “Project Files”, “Work GitHub”, “Team Slack”

Transport: How to communicate with the server

Transport	Use Case
stdio	Command-line MCP servers (most common)
HTTP	HTTP-based MCP servers
SSE	Server-Sent Events servers

For stdio transport:

• Command: The executable to run (e.g., npx, node, python)
• Arguments: Command arguments (e.g., -y @modelcontextprotocol/server-filesystem)

For HTTP/SSE transport:

• URL: The server endpoint URL

Environment Variables: Required credentials or configuration

• Format: KEY=value, KEY2=value2
• Example: GITHUB_TOKEN=ghp_xxx, REPO_OWNER=myorg

Step 4: Test Connection

Click Test Connection to verify the server works. A successful test shows the discovered tools.

Step 5: Save

Click Save to add the server.

Connecting to Servers

Manual Connection

1. Select a server in the list
2. Click Connect
3. Wait for connection (button shows “Connecting…”)
4. When connected, tools appear in the right panel

Disconnecting

1. Select the connected server
2. Click Disconnect

Using MCP Tools in Workflows

Once you have MCP servers configured and connected, you can use their tools in your workflows.

Adding an MCP Step

1. Open Workflows window (Cmd+R)
2. Create or edit a workflow
3. Click Add Step
4. In the Action dropdown, scroll to MCP Tools section
5. Select an MCP tool (format: ServerName: tool_name)

Configuring MCP Tool Arguments

MCP tools often require arguments. You have two options:

Manual Arguments

Specify arguments directly as JSON:

{
  "path": "/Users/me/project",
  "pattern": "*.swift"
}

You can use variables in arguments:

• {content} - Current clipboard/step content
• {type} - Detected content type
• {timestamp} - Current timestamp

AI Orchestration

Enable “Use AI to build arguments” to let the AI automatically construct tool arguments based on the clipboard content and tool schema.

This is useful when:

• The content determines which arguments to use
• Arguments need intelligent interpretation
• You want dynamic, context-aware tool usage

Example MCP Workflows

Example 1: Save Code to Project

Use case: Save AI-generated code directly to your project

Name: Save to Project
Trigger: Code
Steps:
  1. Explain (understand the code)
  2. MCP: Filesystem → write_file
     Arguments: { "path": "/Users/me/project/generated.swift", "content": "{content}" }

Example 2: Create GitHub Issue from Error

Use case: Automatically create a GitHub issue when you copy an error

Name: Error to GitHub Issue
Trigger: Error
Steps:
  1. Search Solutions (get fix suggestions)
  2. MCP: GitHub → create_issue
     AI Orchestration: Enabled
     (AI will format the error and solution as an issue)

Example 3: Search Codebase for Context

Use case: Find related files before explaining code

Name: Contextual Code Explain
Trigger: Code
Steps:
  1. MCP: Filesystem → search_files
     Arguments: { "path": ".", "pattern": "*.swift" }
  2. Explain (with context from search results)

Example 4: Post Summary to Slack

Use case: Summarize content and share with your team

Name: Share Summary to Slack
Trigger: Text
Steps:
  1. Summarize
  2. MCP: Slack → send_message
     Arguments: { "channel": "#general", "text": "{content}" }

Example 5: Database Query Transform

Use case: Query a database and transform results

Name: Query and Format
Trigger: Text (keywords: "query", "sql")
Steps:
  1. MCP: PostgreSQL → query
     AI Orchestration: Enabled
  2. Format JSON
  3. Copy to Clipboard

Example 6: Research with Web Search

Use case: Search the web for information about errors

Name: Research Error
Trigger: Error
Steps:
  1. MCP: Brave Search → search
     AI Orchestration: Enabled
  2. Summarize (compile search results)

Example 7: Browser Automation

Use case: Take a screenshot of a URL

Name: Screenshot URL
Trigger: URL
Steps:
  1. MCP: Puppeteer → screenshot
     Arguments: { "url": "{content}", "fullPage": true }
  2. Save to Desktop

Popular MCP Servers

Each MCP server below requires installation before use. Common installation methods:

Method	Best For	Example
npm install -g	Frequent use, faster startup	npm install -g @modelcontextprotocol/server-filesystem
npx -y	One-time use, no install	npx -y @modelcontextprotocol/server-filesystem
uvx	Python-based servers	uvx mcp-server-sqlite
Docker	Isolated environments	docker run -i mcp/server-filesystem

Filesystem Server

Access and manage local files.

Install globally:

npm install -g @modelcontextprotocol/server-filesystem

Or run with npx (no install):

npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory

Tools:

• read_file - Read file contents
• write_file - Write content to a file
• list_directory - List directory contents
• search_files - Search for files by pattern
• get_file_info - Get file metadata

GitHub Server

Interact with GitHub repositories.

Install globally:

npm install -g @modelcontextprotocol/server-github

Or run with npx:

npx -y @modelcontextprotocol/server-github

Environment Variables:

• GITHUB_TOKEN - Your GitHub personal access token

Tools:

• create_issue - Create a new issue
• list_issues - List repository issues
• create_pull_request - Create a PR
• search_code - Search code in repositories
• get_file_contents - Read repository files

Slack Server

Send messages and interact with Slack.

Install globally:

npm install -g @modelcontextprotocol/server-slack

Or run with npx:

npx -y @modelcontextprotocol/server-slack

Environment Variables:

• SLACK_BOT_TOKEN - Your Slack bot token
• SLACK_TEAM_ID - Your Slack team ID

Tools:

• send_message - Send a message to a channel
• list_channels - List available channels
• search_messages - Search message history

PostgreSQL Server

Query PostgreSQL databases.

Install globally:

npm install -g @modelcontextprotocol/server-postgres

Or run with npx:

npx -y @modelcontextprotocol/server-postgres postgres://user:pass@host:5432/db

Tools:

• query - Execute SQL queries
• list_tables - List database tables
• describe_table - Get table schema

Troubleshooting MCP

Server Won’t Connect

Most Common Issue

The #1 reason servers fail to connect is that the MCP server package isn’t installed. Make sure you’ve run npm install -g @modelcontextprotocol/server-xxx before trying to connect.

Check:

• Is the MCP server package installed? (Run npm list -g to see installed packages)
• Is Node.js installed? (Run node --version in Terminal)
• Are environment variables set correctly?
• Does the command work in Terminal?
• Check Console.app for error messages

Common fixes:

• Install Node.js from nodejs.org
• Install required packages: npm install -g @modelcontextprotocol/server-xxx
• Verify API keys and tokens
• Check network connectivity for HTTP servers

Tools Not Appearing

Check:

• Is the server connected? (green indicator)
• Click Refresh to reload tools
• Some servers require authentication before listing tools

Tool Execution Fails

Check:

• Are arguments formatted correctly as JSON?
• Are required arguments provided?
• Does the tool have necessary permissions?

Tips:

• Use Test Connection to verify server works
• Double-click tool to see required parameters
• Enable AI orchestration for complex argument building

Environment Variables Not Working

Check:

• Format: KEY=value (no spaces around =)
• Multiple variables: KEY1=value1, KEY2=value2
• Sensitive values should not contain commas

Security Considerations

API Keys and Tokens

• Store sensitive tokens as environment variables
• MCP servers run locally on your machine
• Tokens are only sent to the respective services

File Access

• Filesystem server only accesses directories you specify
• Be careful with write permissions
• Use read-only access when possible

Network Access

• MCP servers may make network requests
• Review server documentation for data handling
• Only use trusted MCP servers

Creating Custom MCP Servers

For advanced users, you can create custom MCP servers:

1. Python: Use the mcp Python package
2. TypeScript/JavaScript: Use @modelcontextprotocol/sdk
3. Other languages: Implement the MCP JSON-RPC protocol

See the MCP Documentation for details.

Next Steps

• Workflows Guide: Learn to create workflows using MCP tools
• Features Overview: See all Clipboard Recast capabilities
• AI Providers: Configure your AI provider