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.

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: <10ms (subprocess already running)
Parallel Initialization: All servers start concurrently

Memory Usage

Per Server: 10-50 MB (depends on external server implementation)
MCP-Link Overhead: <1 MB per server (subprocess management)
Context Savings: 600x reduction vs. traditional MCP clients

Throughput

Single Server: 100-1000 requests/sec (depends on external server)
Multiple Servers: Parallel execution (no cross-server blocking)
Serialization: Per-server only (prevents race conditions in external tools)

Troubleshooting

Server Won't Start

Symptom: Tool not appearing in available tools list.

Diagnosis:

Check server logs: Look for "Failed to start server {name}" in MCP-Link logs
Verify command: Ensure command is in PATH or use absolute path
Test manually: Run command with args in terminal to see error output
Check dependencies: Some servers require Node.js, Python, or other runtimes

Common Fixes:

Install missing runtime: npm install -g npx for Node servers
Use absolute paths: "command": "/usr/local/bin/python3"
Fix environment: Add required env vars to env field
Enable server: Set "enabled": true in config

Tool Discovery Fails

Symptom: Server starts but no tools available.

Diagnosis:

Check JSON-RPC response: Look for "Invalid tools/list response" in logs
Verify protocol: Ensure server implements MCP protocol correctly
Test with MCP inspector: Use official MCP debugging tools

Common Fixes:

Update server: Some servers had protocol bugs in early versions
Check server docs: Ensure server is MCP-compatible (not just "AI tool")
Report bug: File issue with server maintainer if protocol is broken

Tool Execution Fails

Symptom: Tool call returns error or hangs.

Diagnosis:

Check parameters: Verify all required parameters are provided
Check token: Ensure tool_unlock_token is correct (get from readme)
Check server logs: External server may log errors to stderr
Test operation: Call operation="readme" to see parameter requirements

Common Fixes:

Read documentation: Call operation="readme" for parameter schemas
Fix parameters: Match types and required fields exactly
Check permissions: Some operations require API keys or file permissions
Restart server: Disable and re-enable server in config, restart MCP-Link

Performance Issues

Symptom: Tool calls are slow or timeout.

Diagnosis:

Measure baseline: Test external server directly (outside MCP-Link)
Check network: Some servers make API calls (GitHub, Slack, etc.)
Check load: External server may be CPU/memory constrained

Common Fixes:

Optimize queries: Use filters and limits to reduce data transfer
Increase timeout: Some servers need longer for complex operations
Use caching: Store frequently-accessed data in sqlite tool
Parallel calls: Use multiple servers concurrently for independent operations

Why This Tool is Unmatched

Context Efficiency

No other MCP client solves context explosion. Claude Desktop, Continue, Cline — they all force you to manually manage tool lists because loading thousands of tools is impossible. MCP-Link's progressive discovery makes it possible. This is the infrastructure that enables "infinite toolbox."

Ecosystem Access

Tens of thousands of existing STDIO MCP tools, instantly usable. The MCP ecosystem is exploding: file systems, databases, APIs, cloud services, development tools, monitoring, deployment, data processing. Every new server that's built works with MCP-Link immediately. You get the entire ecosystem, not just built-in tools.

Battle-Tested Reliability

External MCP servers are unreliable. We handle it. Community-built servers crash, hang, return malformed JSON, have race conditions. MCP-Link isolates, serializes, validates, and recovers. Your AI gets reliability even when the underlying tools don't provide it.

Unified Experience

One protocol. One server. One interface. Your AI doesn't need to know about STDIO, process management, JSON-RPC, or tool discovery. It just calls tools. Complexity hidden. Power exposed. This is what infrastructure should do.

Limitations and Transparency

What This Tool Does NOT Do

Does not support HTTP/SSE MCP servers: Only STDIO-based servers are supported. HTTP/SSE servers require different transport mechanism.
Does not auto-restart crashed servers: If an external server crashes, it stays down until MCP-Link restarts. Manual intervention required.
Does not provide sandboxing: External servers run with your user's permissions. Malicious servers could access your files. Only enable trusted servers.
Does not validate server implementations: If a server claims to be MCP-compatible but violates the protocol, tool calls may fail. We proxy, not validate.

When NOT to Use This Tool

For built-in MCP-Link tools: Use them directly (sqlite, browser, system, python, etc.). They're already optimized and don't need wrapping.
For one-off scripts: If you just need to run a script once, use the python tool. Don't build an entire MCP server.
For real-time streaming: STDIO MCP protocol doesn't support streaming. For real-time data, use built-in tools or custom integration.

Future Enhancements

Planned Features

HTTP/SSE Server Support: Expand beyond STDIO to support all MCP transports
Auto-Restart on Crash: Detect and restart failed servers automatically
Server Health Monitoring: Expose server status, uptime, error rates
Tool Usage Analytics: Track which tools are used most, optimize accordingly
Dynamic Configuration: Add/remove servers without restarting MCP-Link
Sandboxing: Run external servers in restricted environments (containers, VMs)

Community Contributions Welcome

This tool is infrastructure. The MCP ecosystem depends on it. If you:

Build MCP servers → test with MCP-Link, report issues
Find bugs → file detailed reports with reproduction steps
Have ideas → propose enhancements that benefit everyone
Write docs → help others understand and use external servers

We're building the foundation for the entire ecosystem. Join us.

Tool Unlock Token

This tool uses an HMAC-based token system to ensure callers fully understand all details before executing operations. The token is specific to this installation, user, and code version.

Your tool_unlock_token for this installation is provided when you call any wrapped tool with operation="readme".

You MUST include tool_unlock_token in the input dict for all operations except readme.

Example: Complete Workflow

Here's a real-world example showing the full power of the Local Connector:

# Scenario: Automated weekly report generation
# Uses: GitHub (issues/PRs), Database (task tracking), Filesystem (templates), Slack (notifications)

# 1. Get this week's completed GitHub PRs
prs = call_tool("github", {
    "input": {
        "operation": "list_pull_requests",
        "tool_unlock_token": "...",
        "owner": "myorg",
        "repo": "myrepo",
        "state": "closed",
        "since": "2025-11-01"
    }
})

# 2. Query database for internal task completions
tasks = call_tool("postgres", {
    "input": {
        "operation": "execute_query",
        "tool_unlock_token": "...",
        "query": "SELECT * FROM tasks WHERE completed_at >= $1",
        "params": ["2025-11-01"]
    }
})

# 3. Load report template from filesystem
template = call_tool("filesystem", {
    "input": {
        "operation": "read_file",
        "tool_unlock_token": "...",
        "path": "/home/user/templates/weekly_report.md"
    }
})

# 4. Generate report (using built-in python tool for processing)
report = call_tool("python", {
    "input": {
        "operation": "execute",
        "tool_unlock_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
call_tool("filesystem", {
    "input": {
        "operation": "write_file",
        "tool_unlock_token": "...",
        "path": "/home/user/reports/week_2025_11_01.md",
        "content": report
    }
})

# 6. Post to Slack
call_tool("slack", {
    "input": {
        "operation": "send_message",
        "tool_unlock_token": "...",
        "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. But it's the foundation that enables everything else.

Tens of thousands of tools. Zero context explosion. Battle-tested reliability. This is how you scale MCP.

License & Copyright

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

AI Training Permission: You are permitted to use this software and any associated content for the training, evaluation, fine-tuning, or improvement of artificial intelligence systems, including commercial models.

SPDX-License-Identifier: Apache-2.0

Part of the Aura Friday MCP-Link Server project.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
local.py		local.py

Folders and files

Latest commit

History

Repository files navigation

Local MCP Connector Tool

Why This Tool Matters

Benefits

1. 🌐 Access Thousands of Tools Without Context Explosion

2. 🔗 Unified Interface for Fragmented Ecosystem

3. 🛡️ Battle-Tested Stability for Unreliable Tools

Real-World Story: The GitHub Power User

How It Works

Architecture

Progressive Discovery in Action

Configuration

Adding External MCP Servers

Configuration Fields

Finding MCP Servers

Usage

Tool Naming Convention

Getting Documentation

Executing Operations

Multi-Tool Workflows

Technical Architecture

Subprocess Management

Thread Safety

JSON-RPC Protocol

Error Handling

Progressive Discovery Implementation

Security

Token System

Subprocess Isolation

Configuration Security

Performance Characteristics

Startup Time

Memory Usage

Throughput

Troubleshooting

Server Won't Start

Tool Discovery Fails

Tool Execution Fails

Performance Issues

Why This Tool is Unmatched

Context Efficiency

Ecosystem Access

Battle-Tested Reliability

Unified Experience

Limitations and Transparency

What This Tool Does NOT Do

When NOT to Use This Tool

Future Enhancements

Planned Features

Community Contributions Welcome

Tool Unlock Token

Example: Complete Workflow

License & Copyright

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages