MCP Servers with Claude Skills: Setup Guide

This guide walks you through connecting Model Context Protocol (MCP) servers to Claude Skills, letting Claude pull in live data or take actions through external tools. You’ll configure the server, register it in Claude’s settings, and test the integration. Before starting, make sure you have Claude Desktop or Claude Code installed and a basic familiarity with editing JSON configuration files.

What You’ll Need

• Claude Desktop (latest version) or Claude Code CLI
• An MCP server you want to connect (e.g., a filesystem, database, or custom tool server)
• Node.js (v18+) or Python 3.10+ if running an MCP server locally
• A text editor for editing configuration files
• Basic terminal/command-line comfort

Step-by-Step

1. Identify your MCP server’s command or URL. If it’s a local server, note the executable path and any arguments (e.g., npx @modelcontextprotocol/server-filesystem /path/to/folder). If it’s remote, note the HTTP or SSE URL.
2. Locate Claude’s configuration file. For Claude Desktop on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%\Claude\claude_desktop_config.json. For Claude Code, it’s ~/.claude.json or a project-level .mcp.json.
3. Open the configuration file in your text editor. If it doesn’t exist, create it as an empty JSON object {}.
4. Add the MCP server entry. Inside the JSON, add a key "mcpServers" (if not present) and then add your server. For a local server, use the command and args fields. For remote, use url. Example for local filesystem server:

   {
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"]
       }
     }
   }

5. Save the file and restart Claude Desktop completely (quit from the menu bar, not just close the window). For Claude Code, restart the session or run claude mcp list to see if it picks up the change.
6. Verify the server is connected. In Claude Desktop, look for a hammer or plug icon in the input box—click it to see available MCP tools. In Claude Code, run claude mcp list to confirm the server shows as “connected”.
7. Test with a simple prompt. Ask Claude to use the tool, e.g., “List the files in my Documents folder” (if you connected a filesystem server). If it responds with data, the integration works.
8. Troubleshoot if needed. If the tool doesn’t appear, check the server’s logs. For local servers, run the command manually in a terminal to see if it starts without errors. For remote servers, verify the URL is reachable.

Common Mistakes

• Incorrect JSON syntax. A missing comma or quote breaks the entire config. Validate with a JSON linter.
• Using the wrong config file. Claude Desktop and Claude Code have different files—editing one does not affect the other.
• Not restarting Claude. Config changes only load on a fresh start.
• Path issues. For local servers, use absolute paths, not relative ones. On Windows, escape backslashes (\\) in JSON.
• Missing environment variables. Some servers need API keys or tokens set in the env field. Add them as a JSON object under env.

Tips

• Start with one server at a time to isolate issues.
• Use npx -y for Node-based servers to avoid version conflicts.
• For sensitive credentials, use environment variables in the env block rather than hardcoding them in the config.
• Check the MCP server’s documentation for required arguments—many need a path, URL, or API key.
• If you’re developing a custom server, run it in debug mode with verbose logging to see what Claude sends and receives.

Troubleshooting

Server not showing up in Claude: First, verify the config file is valid JSON and the server name is spelled correctly. Restart Claude completely. If still missing, run the server command manually—if it errors, fix that first. For remote servers, test the URL with curl.

Claude says “tool not found”: The server may be connected but the tool name is different. Check the server’s list of tools (often in its README or by running claude mcp get <name> in Claude Code).

Server connects but returns errors: Look at the server’s logs. In Claude Desktop, you can see logs in ~/Library/Logs/Claude (macOS) or %APPDATA%\Claude\logs (Windows). For Claude Code, run with --debug to see detailed output.

Config file ignored: Make sure you’re editing the correct file for your installation. If you have multiple versions of Claude, check each config path. Also ensure the file is named exactly as expected (e.g., claude_desktop_config.json).

Permission errors on local server: The server may not have access to the paths you specified. Grant read/write permissions to the folder or run Claude as an administrator (not recommended for security).

Frequently Asked Questions

Can I connect multiple MCP servers at once?

Yes. Add each server as a separate key under mcpServers. Claude will expose all their tools, though having too many may clutter the interface.

Do I need to code to set this up?

No. You only edit a JSON file. However, if you’re creating your own MCP server, you’ll need programming knowledge in Python or JavaScript/TypeScript.

What’s the difference between MCP servers and Claude Skills?

MCP servers provide external tools/data to Claude, while Skills are custom instructions or workflows you define. They can work together—a Skill might instruct Claude to use a specific MCP tool.

Is it safe to give Claude access to my filesystem?

Only if you trust the server and limit the paths. Use a dedicated folder rather than your entire home directory. Never grant access to sensitive system files.

Why does my server work in Claude Code but not Claude Desktop?

They use separate config files and may have different versions of the MCP protocol. Ensure both are updated and that the server supports the protocol version used by each.

Can I use a remote MCP server hosted on the internet?

Yes, if it exposes an HTTP or SSE endpoint. Add it with a url field instead of command. Be aware of security implications—only connect to servers you trust.

Related

• Handwriting Recognition in OneNote: How to Use It
• Get Workbook Path Only: 5 Quick Ways
• Beginner Dual Booting Mistakes: 7 to Avoid