Skip to content

Instantly share code, notes, and snippets.

@eonist

eonist/local mcp server.md

Created July 16, 2025 10:56
Show Gist options
  • Save eonist/59e2753f4e4f80414bd06979ef2d58a1 to your computer and use it in GitHub Desktop.
Save eonist/59e2753f4e4f80414bd06979ef2d58a1 to your computer and use it in GitHub Desktop.
Download ZIP
local mcp server
Raw
local mcp server.md

Cline AI Agent MCP Configuration for Local Servers

To connect your Cline AI agent to a local MCP server, you'll need to configure it using the STDIO transport method, which is designed specifically for local servers running on your machine[1].

Configuration File Location

Cline stores all MCP server settings in a file called cline_mcp_settings.json[1]. This file uses a JSON format with an mcpServers object containing your server configurations.

Basic Configuration Structure

Here's the typical structure for connecting to a local MCP server:

{
  "mcpServers": {
    "your-server-name": {
      "command": "python",
      "args": ["/path/to/your/server.py"],
      "env": {
        "API_KEY": "your_api_key"
      },
      "alwaysAllow": ["tool1", "tool2"],
      "disabled": false
    }
  }
}

Configuration Parameters

Required Parameters

  • command: The executable command to run your local server (e.g., "python", "node", "npx")
  • args: Array of arguments passed to the command, typically including the path to your server script

Optional Parameters

  • env: Environment variables to inject into the server process (useful for API keys or configuration)
  • alwaysAllow: Array of tool names that should be automatically allowed without confirmation
  • disabled: Boolean to enable/disable the server (defaults to false)

Common Configuration Examples

Python MCP Server

{
  "mcpServers": {
    "my-python-server": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "DATABASE_URL": "sqlite:///local.db"
      }
    }
  }
}

Node.js MCP Server

{
  "mcpServers": {
    "my-node-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "PORT": "3000"
      }
    }
  }
}

NPX-based Server

{
  "mcpServers": {
    "sqlite-server": {
      "command": "npx",
      "args": ["-y", "mcp-sqlite", "/path/to/database.db"]
    }
  }
}

Configuration Through UI

You can also configure MCP servers through Cline's interface[1]:

  1. Click the MCP Servers icon in the top navigation bar
  2. Select the "Installed" tab
  3. Click "Configure MCP Servers" at the bottom
  4. Add your server configuration through the UI

Additional Settings

Network Timeout

You can set the maximum response time for MCP server tool calls using the Network Timeout dropdown, with options ranging from 30 seconds to 1 hour (default is 1 minute)[1].

MCP Mode Control

Cline allows you to restrict or disable MCP server functionality entirely using the Cline>Mcp:Mode setting[1].

Best Practices

  1. Use absolute paths for your server executables and scripts
  2. Set appropriate environment variables for configuration rather than hardcoding values
  3. Test your server independently before adding it to Cline
  4. Use the alwaysAllow parameter for frequently-used, trusted tools to reduce confirmation prompts

This configuration will enable your Cline AI agent to communicate with your local MCP server using the STDIO transport protocol, allowing seamless integration of your custom tools and capabilities.

[1] https://github.com/lastmile-ai/mcp-agent [2] https://modelcontextprotocol.io/clients [3] https://github.com/mcp-use/mcp-use [4] https://dzone.com/articles/mcp-client-agent-architecture-amp-implementation [5] https://openai.github.io/openai-agents-python/mcp/ [6] https://code.visualstudio.com/docs/copilot/chat/mcp-servers [7] https://docs.mistral.ai/agents/mcp/ [8] https://learn.microsoft.com/en-us/dynamics365/customer-service/administer/configure-ai-agent-to-use-mcp-server [9] https://docs.anthropic.com/en/docs/claude-code/mcp [10] https://dev.to/debs_obrien/building-your-first-mcp-server-a-beginners-tutorial-5fag [11] https://huggingface.co/learn/mcp-course/en/unit1/mcp-clients [12] https://docs.continue.dev/customize/deep-dives/mcp [13] https://www.mcpworld.com/en/detail/4d6d346fbbd6c049cc34b7f719c1b7d3 [14] https://www.pulsemcp.com/posts/introduction-to-fast-agent-mcp-client [15] https://modelcontextprotocol.io/quickstart/user [16] https://www.youtube.com/watch?v=aiH79Q-LGjY [17] https://modelcontextprotocol.io/quickstart/server [18] https://docs.cline.bot/mcp/configuring-mcp-servers [19] https://dev.to/developer_harsh/how-to-build-mcp-servers-and-test-locally-from-scratch-3d4j [20] https://www.reddit.com/r/ClaudeAI/comments/1ll88ay/local_mcp_servers_can_now_be_installed_with_one/

@eonist
Copy link
Author

eonist commented Jul 16, 2025

Using MCP Inspector: Web Browser Interface Guide

Yes, MCP Inspector is designed to open a web browser - that's the intended behavior! The Inspector runs as a web-based tool that provides a visual interface for testing and debugging MCP servers. Here's how to use it effectively:

Understanding the MCP Inspector Architecture

When you run npx @modelcontextprotocol/inspector, it starts two components[1][2]:

  • MCP Inspector Client (MCPI): A React-based web UI (default port 6274)
  • MCP Proxy (MCPP): A Node.js server that bridges the web UI to your MCP server (default port 6277)

The web browser interface at http://localhost:6274 is where you'll interact with your MCP server[3][4].

Getting Started with the Web Interface

1. Launching the Inspector

Start the Inspector with your MCP server command:

# Basic usage
npx @modelcontextprotocol/inspector node /path/to/your/server.js

# With environment variables
npx @modelcontextprotocol/inspector -e API_KEY=your_key -- node /path/to/server.js

# With custom ports
CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node /path/to/server.js

2. Accessing the Web Interface

Once started, you'll see output like:

Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274

Open your browser and navigate to http://localhost:6274 (or the custom port you specified)[3][4].

Using the Web Interface

Step 1: Connect to Your Server

  1. Click the "▶︎Connect" button on the left sidebar[3]
  2. Select transport type: Choose stdio (recommended for local servers)[4]
  3. Verify environment variables: Ensure any required environment variables are set
  4. Click "Connect" to establish the connection

Step 2: Explore the Main Tabs

The Inspector provides three main tabs for testing your MCP server[3][4]:

Tools Tab

  • View all registered tools provided by your server
  • See tool schemas and descriptions
  • Test tools with custom inputs using a JSON editor
  • Execute tools and view their responses
  • Monitor execution results in real-time

Resources Tab

  • Browse available resources exposed by your server
  • View resource metadata and descriptions
  • Test resource content retrieval
  • Test subscriptions (if your server supports them)

Prompts Tab

  • View available prompt templates
  • Test prompts with different arguments
  • Preview generated messages
  • Experiment with prompt variations

Step 3: Testing Your MCP Server

Example testing workflow[5]:

  1. Select a tool from the Tools tab
  2. Enter test inputs in the JSON editor
  3. Execute the tool by clicking the run button
  4. Review the response and debug any issues
  5. Iterate with different inputs to test edge cases

Key Features and Benefits

Visual Interface Benefits

  • No client code required: Test your server without writing MCP client applications[6]
  • Real-time interaction: See immediate responses to your requests
  • Interactive debugging: Modify inputs and test different scenarios quickly
  • Visual feedback: Clear indication of connection status and server health

Authentication Support

For servers requiring authentication[4]:

  • Enter your Bearer Token in the designated field
  • Specify custom header names if different from default Authorization
  • Test authenticated endpoints securely

Configuration Export

The Inspector can export server launch configurations for use in other MCP clients like Cursor or Claude Desktop[2].

Advanced Usage Tips

CLI Mode for Automation

You can also use the Inspector in command-line mode for scripting[4]:

# List available tools
npx @modelcontextprotocol/inspector --cli -e API_KEY=your_key -- node server.js --method tools/list

# Call a specific tool
npx @modelcontextprotocol/inspector --cli -e API_KEY=your_key -- node server.js --method tools/call --tool-name search --tool-arg query="test"

Custom Port Configuration

If the default ports conflict with other services[2]:

CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node server.js

Troubleshooting Common Issues

Connection Problems

  • Verify your server is running and accessible
  • Check for port conflicts with other services
  • Review server logs for error messages
  • Ensure environment variables are properly set

Authentication Issues

  • Double-check API keys and tokens
  • Verify header names match your server's expectations
  • Test authentication independently before using the Inspector

Why Use the Web Interface?

The browser-based interface is particularly valuable because it allows you to:

  • Test end-to-end functionality without connecting to a full MCP client like Claude Desktop[3]
  • Debug specific features in isolation
  • Iterate quickly during development
  • Visualize server responses in a user-friendly format
  • Save time compared to writing custom test scripts

The MCP Inspector's web interface transforms what could be a complex debugging process into an intuitive, visual experience that accelerates your MCP server development workflow.

[1] https://modelcontextprotocol.io/docs/tools/inspector
[2] https://github.com/modelcontextprotocol/inspector
[3] https://en.bioerrorlog.work/entry/how-to-use-mcp-inspector
[4] https://www.mcpevals.io/blog/mcp-inspector-guide
[5] https://mcp-framework.com/docs/debugging/
[6] https://bootcamptoprod.com/mcp-inspector-guide/
[7] https://www.youtube.com/watch?v=98l_k0XYXKs
[8] https://www.apollographql.com/tutorials/intro-mcp-graphql/04-defining-inspecting-operations
[9] https://github.com/9pros/MCP-Browser-Inspector
[10] https://mcp.so/client/online-mcp-inspector/web-mcp
[11] https://modelcontextprotocol.io/
[12] https://www.youtube.com/watch?v=Y0tZ35dFFx4
[13] https://simplescraper.io/blog/how-to-mcp
[14] https://developers.cloudflare.com/agents/guides/test-remote-mcp-server/
[15] https://browsermcp.io/
[16] https://modelcontextprotocol.io/docs/tools/debugging
[17] https://playbooks.com/mcp/jovanipink-browser-use
[18] https://www.apollographql.com/tutorials/intro-mcp-graphql/04-the-mcp-inspector

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment