Local Mcp

Local MCP Connector Tool

A tool which bridges STDIO-based MCP tools, to SSE, intelligently bringing tens of thousands of new tools to your AI's fingertips (wrapped with progressive-disclosure, so zero token wastage!)

Unlock tens of thousands of MCP tools — without exploding your context.

[](LICENSE) [](https://www.python.org/) [](https://github.com/AuraFriday/mcp-link-server)

---

Why This Tool Matters

The MCP ecosystem has tens of thousands of STDIO-based tools. File systems, databases, APIs, cloud services, development tools, data processors — an endless universe of capabilities.

The problem? Traditional MCP clients force you to manually enable/disable tools one-by-one. Your context explodes. You spend more time managing tools than using them. It's unusable at scale.

The solution: MCP-Link's Local Connector wraps every external STDIO MCP tool in a progressive discovery layer. All tools are available, all the time — but their full schemas only load when needed. Your AI can access thousands of tools without wasting a single token on tools it's not using.

This is the infrastructure that makes MCP-Link's "infinite toolbox" possible.

---

Benefits

1. 🌐 Access Thousands of Tools Without Context Explosion

Every STDIO MCP tool, instantly available — zero context waste. The Local Connector automatically discovers and wraps all external MCP servers configured in your settings. Each tool uses progressive discovery: minimal footprint until needed, full documentation on demand. Your AI can have 100+ tools available while using the context of 3.

2. 🔗 Unified Interface for Fragmented Ecosystem

One protocol. One server. Every tool. The MCP ecosystem is fragmented: different servers, different transports, different conventions. The Local Connector bridges them all through MCP-Link's SSE transport. Your AI doesn't need to know about STDIO, process management, or JSON-RPC — it just calls tools. Complexity hidden. Power exposed.

3. 🛡️ Battle-Tested Stability for Unreliable Tools

Isolation, error handling, and graceful degradation. External MCP servers crash. They hang. They return malformed responses. The Local Connector isolates each server in its own subprocess, serializes requests to prevent race conditions, and handles failures gracefully. If a server dies, only its tools become unavailable — everything else keeps working. Your AI gets reliability even when the underlying tools don't provide it.

---

Real-World Story: The GitHub Power User

Sarah is a developer who uses 47 different MCP tools daily: GitHub operations, file system access, database queries, API integrations, code analysis, deployment tools, monitoring dashboards.

Before MCP-Link: She used Claude Desktop with 8 manually-enabled tools. Every task required disabling some tools and enabling others. Her context was always full. She spent 20% of her time managing tool configurations. Complex workflows that needed 15+ tools? Impossible.

After MCP-Link: She added all 47 tools to her local_mcpServers config once. Now they're always available. Her AI can:

• Search GitHub issues → query database → update spreadsheet → post Slack notification
• Read local files → analyze with custom tool → commit to GitHub → trigger deployment
• Monitor production → query logs → file bug report → assign to team member

All in one conversation. Zero tool management. Her context usage dropped 80% because only the tools she's actively using consume tokens.

The result: Sarah's AI went from "helpful assistant" to "autonomous co-worker." Complex multi-tool workflows that were impossible are now routine. She ships features 3x faster.

---

How It Works

Architecture

┌─────────────────────────────────────────────────────────────┐
│ MCP-Link SSE Server (Your AI connects here)                 │
│  ├─ Built-in tools (sqlite, browser, system, python...)     │
│  └─ Local Connector (this tool)                             │
│      ├─ Reads settings[0].local_mcpServers config           │
│      ├─ Starts STDIO subprocess for each enabled server     │
│      ├─ Discovers tools via JSON-RPC tools/list             │
│      ├─ Wraps each tool in progressive discovery layer      │
│      └─ Proxies tool calls via JSON-RPC tools/call          │
└─────────────────────────────────────────────────────────────┘
         ↓                    ↓                    ↓
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ GitHub MCP   │    │ Filesystem   │    │ Custom Tool  │
│ Server       │    │ MCP Server   │    │ MCP Server   │
│ (STDIO)      │    │ (STDIO)      │    │ (STDIO)      │
└──────────────┘    └──────────────┘    └──────────────┘

Progressive Discovery in Action

Traditional MCP Client:

Tool Registry (loaded into context):
├─ github_create_issue: {full 200-line schema}
├─ github_update_issue: {full 200-line schema}
├─ github_list_issues: {full 200-line schema}
├─ ... 44 more GitHub tools with full schemas ...
└─ Total: 9,000 tokens wasted before AI does anything

MCP-Link Local Connector:

Tool Registry (loaded into context):
├─ github: "Use for GitHub operations. Call with operation='readme' for details."
└─ Total: 15 tokens

When AI needs GitHub:
AI: {operation: "readme"}
Tool: Returns full documentation for all GitHub operations
AI: {operation: "create_issue", title: "Bug", body: "..."}
Tool: Executes and returns result

Result: 600x reduction in wasted context. Thousands of tools available with the footprint of a handful.

---

Configuration

Adding External MCP Servers

External MCP servers are configured in settings[0].local_mcpServers in your nativemessaging.json:

{
  "settings": [
    {
      "local_mcpServers": {
        "github": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
          },
          "ai_description": "Use this tool when you need to perform GitHub operations like managing issues, pull requests, repositories, workflows, and code scanning."
        },
        "filesystem": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
          "ai_description": "Use this tool when you need to read, write, or manage files in the user's projects directory."
        },
        "postgres": {
          "enabled": false,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
          "ai_description": "Use this tool when you need to query or modify the PostgreSQL database."
        }
      }
    }
  ]
}

Configuration Fields

• enabled (boolean, required): Whether this server should be started. Set to false to temporarily disable without removing configuration.
• command (string, required): The executable to run (e.g., "npx", "python", "node", "/path/to/binary").
• args (array of strings, optional): Command-line arguments passed to the command.
• env (object, optional): Environment variables to set for the subprocess (e.g., API keys, database URLs).
• ai_description (string, optional but recommended): A description that helps the AI understand when to use this tool. This appears in the tool's top-level description.

Finding MCP Servers

The MCP ecosystem has hundreds of community-built servers:

• Official Servers: https://github.com/modelcontextprotocol
• Community Servers: https://github.com/topics/mcp-server
• Server Registry: https://mcp-registry.com (if available)

Popular servers include:

• @modelcontextprotocol/server-github - GitHub operations
• @modelcontextprotocol/server-filesystem - File system access
• @modelcontextprotocol/server-postgres - PostgreSQL database
• @modelcontextprotocol/server-slack - Slack messaging
• @modelcontextprotocol/server-google-drive - Google Drive access
• @modelcontextprotocol/server-memory - Persistent memory
• And thousands more...

---

Usage

Tool Naming Convention

External tools are automatically wrapped and exposed with this naming pattern:

{server_name}

For example:

• github (wraps all GitHub MCP server tools)
• filesystem (wraps all Filesystem MCP server tools)
• postgres (wraps all Postgres MCP server tools)

Getting Documentation

Every wrapped tool supports the readme operation:

# Get full documentation for a server's tools
result = call_tool("github", {
    "input": {
        "operation": "readme"
    }
})

# Returns:
# - tool_unlock_token for this installation
# - List of all available operations
# - Full parameter schemas for each operation
# - Usage examples

Executing Operations

Once you have the documentation and tool_unlock_token, execute operations:

# Create a GitHub issue
result = call_tool("github", {
    "input": {
        "operation": "create_issue",
        "tool_unlock_token": "abc123...",
        "owner": "myorg",
        "repo": "myrepo",
        "title": "Bug: Login fails",
        "body": "Steps to reproduce:\n1. ...",
        "labels": ["bug", "high-priority"]
    }
})

Multi-Tool Workflows

The real power is combining multiple external tools:

# Complex workflow: GitHub → Database → Slack
# 1. List open GitHub issues
issues = call_tool("github", {
    "input": {
        "operation": "list_issues",
        "tool_unlock_token": "...",
        "owner": "myorg",
        "repo": "myrepo",
        "state": "open"
    }
})

# 2. Store in database
for issue in issues:
    call_tool("postgres", {
        "input": {
            "operation": "execute_query",
            "tool_unlock_token": "...",
            "query": "INSERT INTO issues (id, title, state) VALUES ($1, $2, $3)",
            "params": [issue['id'], issue['title'], issue['state']]
        }
    })

# 3. Send Slack notification
call_tool("slack", {
    "input": {
        "operation": "send_message",
        "tool_unlock_token": "...",
        "channel": "#engineering",
        "text": f"Found {len(issues)} open issues"
    }
})

---

Technical Architecture

Subprocess Management

Each enabled MCP server runs in an isolated subprocess:

• Process Creation: subprocess.Popen with STDIO pipes
• Encoding: UTF-8 with error replacement (handles malformed output)
• Buffering: Unbuffered (bufsize=0) for real-time communication
• Console Hiding: CREATE_NO_WINDOW flag on Windows (no console flashing)
• Lifecycle: Started on server init, terminated on server shutdown

Thread Safety

All communication with external servers is thread-safe:

• Per-Server Locks: Each server has a dedicated threading.Lock
• Request Serialization: Only one request per server at a time (prevents race conditions)
• Request IDs: Monotonic counter per server for JSON-RPC correlation
• Initialization Lock: Thread-safe lazy initialization on first use

JSON-RPC Protocol

Communication with external servers uses JSON-RPC 2.0 over STDIO:

Tool Discovery:

→ {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
← {"jsonrpc": "2.0", "id": 1, "result": {"tools": [...]}}

Tool Execution:

→ {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "create_issue", "arguments": {...}}}
← {"jsonrpc": "2.0", "id": 2, "result": {"content": [{"type": "text", "text": "..."}]}}

Error Handling

The connector handles all failure modes gracefully:

• Server Start Failure: Logged, server skipped, other servers continue
• Tool Discovery Failure: Logged, server marked as unavailable
• Communication Timeout: No response → error returned to AI
• Malformed Response: JSON parse error → error returned to AI
• Server Crash: Subsequent calls return "server not available" error
• Invalid Tool Call: Parameter validation → error with helpful message

Progressive Discovery Implementation

Each external server is wrapped as a single unified tool:

Advertised Schema (minimal):

{
    "name": "github",
    "description": "Use this tool when you need GitHub operations...",
    "parameters": {
        "properties": {
            "input": {
                "type": "object",
                "description": "Use {\"input\":{\"operation\":\"readme\"}} for docs"
            }
        }
    }
}

Full Schema (on-demand):

# Only loaded when AI calls operation="readme"
{
    "operations": [
        {
            "name": "create_issue",
            "description": "Create a new issue",
            "parameters": {
                "owner": {"type": "string", "required": true},
                "repo": {"type": "string", "required": true},
                "title": {"type": "string", "required": true},
                # ... full schema ...
            }
        },
        # ... 46 more operations ...
    ]
}

Result: 600x context reduction. Thousands of tools with minimal footprint.

---

Security

Token System

Every operation (except readme) requires a tool_unlock_token:

• Generation: HMAC-based, unique per installation/user/code version
• Purpose: Ensures AI has read full documentation before executing
• Validation: Server-side check before proxying to external tool
• Rotation: Automatic on server restart or code update

Subprocess Isolation

External servers run in isolated subprocesses:

• No Shared Memory: Each server has independent memory space
• No Direct Access: External servers cannot access MCP-Link internals
• Controlled Communication: Only JSON-RPC over STDIO pipes
• Resource Limits: OS-level process isolation and resource management

Configuration Security

Server configurations are stored in nativemessaging.json:

• File Permissions: User-only read/write (OS-enforced)
• Environment Variables: Secrets passed via env field (not command-line)
• No Auto-Enable: Servers must be explicitly enabled by user
• Validation: Command and args validated before subprocess creation

---

Performance Characteristics

Startup Time

• First Call: 100-500ms (subprocess start + tool discovery)
• Subsequent Calls: = $1",

"params": ["2025-11-01"] } })

3. Load report template from filesystem

template = calltool("filesystem", { "input": { "operation": "readfile", "toolunlocktoken": "...", "path": "/home/user/templates/weekly_report.md" } })

4. Generate report (using built-in python tool for processing)

report = calltool("python", { "input": { "operation": "execute", "toolunlock_token": "...", "code": f""" import json prs = {json.dumps(prs)} tasks = {json.dumps(tasks)} template = {json.dumps(template)}

Process data and fill template

... (report generation logic) ...

result = filled_report """ } })

5. Save report to filesystem

calltool("filesystem", { "input": { "operation": "writefile", "toolunlocktoken": "...", "path": "/home/user/reports/week202511_01.md", "content": report } })

6. Post to Slack

calltool("slack", { "input": { "operation": "sendmessage", "toolunlocktoken": "...", "channel": "#engineering", "text": "📊 Weekly report generated and saved!", "attachments": [{"text": report[:500] + "..."}] } })

**Result:** A complex 6-tool workflow that would be impossible with traditional MCP clients (context explosion) works seamlessly with MCP-Link. All tools available, minimal context waste, reliable execution.

---

**The Local MCP Connector is the infrastructure that makes MCP-Link's "infinite toolbox" possible. It's not flashy. It's not user-facing

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AuraFriday](https://github.com/AuraFriday)
- **Source:** [AuraFriday/local_mcp](https://github.com/AuraFriday/local_mcp)
- **License:** Apache-2.0
- **Homepage:** https://aurafriday.com/

Install and usage instructions live in the source repository linked above.