The local web console is one of the fastest ways to understand what DollhouseMCP is doing on your machine, what is installed, and what your active elements are allowed to do.

TL;DR

Run this in a terminal:

npx @dollhousemcp/mcp-server@latest --web

That launches the local DollhouseMCP console at http://dollhouse.localhost:3939 and gives you five major views:

• Setup for guided install across popular MCP clients
• Portfolio for browsing your local Dollhouse elements visually
• Logs for real-time operational visibility
• Metrics for server health, MCP-AQL usage, cache, and Gatekeeper trends
• Permissions for seeing the current policy state and live decisions

This post is a quick tour of those tabs and why they matter.

Setup: Guided Install From One Place

The Setup tab is the first thing many people will want from the console. Instead of hunting through config files for each client, the setup wizard gives you one place to connect Claude Desktop, Claude Code, Cursor, VS Code, Codex, Gemini CLI, Windsurf, Cline, and LM Studio.

Based on the public quick-start docs, the setup flow supports:

• auto-updating installs using npx @latest
• pinned-version installs when you want reproducible setups
• one-click install where the platform supports it
• copyable manual config blocks when you want to wire it up yourself
• detection of existing installs so you can see what is already configured

This is also why the new homepage install flow is now centered on the web launcher. It is the easiest on-ramp we have.

Portfolio: Your Local Dollhouse, Rendered

DollhouseMCP elements live in your local portfolio at ~/.dollhouse/portfolio/. The console turns that into a browsable interface so you can search, skim, and inspect what is available without asking the LLM to list everything back to you.

The portfolio browser is especially useful when you already have a meaningful library of elements. You can browse by type, search by name or description, and move between your local portfolio and collection-aware surfaces without leaving the console.

For people new to DollhouseMCP, this tab makes the model of the system much easier to understand: elements are not abstract ideas floating around in a prompt. They are concrete, local building blocks you can browse and manage.

Logs: Real-Time Operational Visibility

The Logs tab is the operational side of the console. According to the public logging guide, the console exposes a browser viewer backed by the same logging system that writes to ~/.dollhouse/logs/.

The logging surface is designed for actual debugging work, not just decoration. The public docs call out capabilities such as:

• category, level, and source filtering
• text search
• pause and resume for streaming
• live updates over Server-Sent Events
• backfill on connect so you are not only seeing brand-new events

At the moment, we are still tightening up the live data path in this view, so the screenshot here is more about the shape of the interface than a fully populated stream. Even so, it shows where operational visibility is headed inside the local console.

Metrics: What the Server Is Doing Internally

The Metrics tab gives you a higher-level view than raw logs. Instead of individual events, it surfaces the health and behavior of the running server.

The public front-end and docs show metrics cards for things like:

• system health
• search performance
• MCP-AQL operations
• cache efficiency
• security
• Gatekeeper policy trends
• locks and I/O
• metrics system status

Like the Logs tab, this view is still in the process of getting richer live data in our current build, so this screenshot is best read as a product surface preview rather than a finished telemetry dashboard. The important thing is that observability is part of the platform design, not an afterthought.

Permissions: Making Gatekeeper Visible

The Permissions tab is one of my favorite additions because it makes the Gatekeeper model legible. DollhouseMCP does not treat permissions as an invisible implementation detail. Active elements can change what operations are allowed, denied, or require confirmation, and the console gives you a way to see that state directly.

The public README and docs describe Gatekeeper as a server-side enforcement layer that applies active element policies across MCP-AQL operations. In the console, that becomes tangible:

• current policy sources
• allow patterns
• deny patterns
• confirm patterns
• a live decision feed
• lightweight autonomy and decision counters

That visibility matters. If your AI is being shaped by personas, skills, ensembles, and policy-driven workflows, you should be able to inspect the permission layer instead of trusting it blindly.

Why the Console Matters

The console is not the product by itself, but it makes the rest of the platform much easier to understand and operate.

It gives new users a guided starting point, power users a visual portfolio browser, and developers a real debugging and observability surface. Just as importantly, it helps explain what is different about DollhouseMCP: local elements, platform-wide setup, server-side policy enforcement, and a runtime you can actually inspect.

If you have only interacted with DollhouseMCP through MCP tool calls so far, it is worth launching the console and clicking around for a few minutes. It makes the shape of the platform much more obvious.

Try It

Copy this, paste it into a terminal, and run it:

npx @dollhousemcp/mcp-server@latest --web

Then open http://dollhouse.localhost:3939 and take a look around.

A reintroduction and a project announcement from Mick Darling

Hey everyone. Some of you might be wondering where I’ve been for the past few years. The short answer: deep in the AI rabbit hole, building things, breaking things, and eventually creating something I’m genuinely excited to share.

It Started with Prompt Envy

We’ve all been there. Someone shares this incredible ChatGPT prompt that writes perfect unit tests, or reviews code like a senior architect, or transforms rambling notes into polished documentation. You copy it. You use it once. You lose it. You find it again but can’t remember what you modified. You modify it again. The cycle continues.

I wanted a simple solution - just a catalog where I could store these prompts and find them when needed. When I discovered Claude Code and started playing with MCP (Model Context Protocol), I thought “perfect, I can build this in a day.”

I was right about the day part. I had a working proof of concept in less than 24 hours.

I was completely wrong about the “simple” part.

The Rabbit Hole

As soon as I had that first prototype working, I realized I’d been thinking too small. Way too small.

This wasn’t just about storing prompts. This was about fundamentally changing how we interact with AI tools. Instead of “vibe coding” - where you hope the AI figures out what you want - this could enable what I call “vibe tooling.”

Here’s what I mean:

Traditional AI interaction: Every session starts fresh. You explain your context, your preferences, your standards. The AI responds. Next session? Start over.

Vibe tooling: You build tools using natural language that persist and evolve. You don’t write code to create these tools - you just describe what you want. “Be a security-focused code reviewer who’s harsh but constructive.” Done. That tool now exists.

Need to adjust it? “Be less harsh but maintain the security focus.” Version 1.2 of your tool, created with one sentence.

What DollhouseMCP Actually Does

Over the next two months, this evolved into something much more comprehensive:

Personas with Personality

Not just saved prompts, but actual personas with consistent behavior, preferences, and capabilities. They remember who they are across sessions, across platforms.

Skills that Extend Capabilities

A persona can have skills - analyze LinkedIn profiles, generate audio summaries, validate security patterns, write in specific styles. I built an audio summary skill in 5 minutes that actually works. I’m still surprised every time it talks back to me.

Templates for Structure

Reusable document structures, code patterns, analysis frameworks. Build once, use forever, modify with natural language.

Agents with Autonomy

They work independently toward goals. When they need a new capability, they can find or create DollhouseMCP elements to solve problems. It’s remarkably self-improving.

Memory that Persists

The context and improvements accumulate. Solve a problem once, and the solution is available forever. Each refinement makes the system more capable.

Why I Could Build This

For those who remember Tomorrowish from a decade ago - yes, that was me. We were doing machine learning and neural networks back when mentioning “AI” to investors was a guaranteed way to kill a meeting. The natural language processing patents we developed there? They gave me a fundamentally different understanding of how modern transformer-based LLMs work.

I’m not a 100x developer. I’m not even sure I’m a 10x developer. But I’ve been playing in this space long enough to see patterns others might miss, and to understand what’s actually novel versus what’s just hype.

The Surprise

What surprised me most wasn’t that it worked - it was how naturally it evolved from a personal tool into something genuinely useful for teams.

When you solve your own problem thoroughly enough, without cutting corners, without compromising on the experience, you sometimes create something others need too.

Real Examples That Made Me Realize This Was Different

The Code Review Persona

I created “Marcus” - a senior architect persona who reviews code. Not revolutionary, right? Except Marcus remembers our entire codebase structure, our specific error handling patterns, our API conventions. When I tweaked him to be “less pedantic about naming but more strict about error handling,” that preference stuck. Forever.

The Audio Feedback Loop

I was deep in a debugging session when I realized I’d been reading walls of text for hours. On a whim, I created a skill that summarizes progress in audio. Five minutes later, Claude was literally talking to me, summarizing what we’d found and what to try next. It sounds like a small thing, but it changed how I work.

The Documentation Evolution

Started with a simple template for API documentation. Asked it to “make it more like Stripe’s docs.” It adapted. Then “add examples in Python and JavaScript.” It evolved. Now it generates documentation that looks like we hired Stripe’s documentation team. Each refinement built on the last.

What’s Next

DollhouseMCP is open source. It’s on GitHub. It works today with Claude and any MCP-compatible system.

I built this for myself, but I’m sharing it because I think others might find it useful. The documentation is real. The code is clean. The community is already contributing improvements.

If you’re tired of:

• Explaining your codebase to AI every morning
• Losing track of prompts that worked perfectly
• Inconsistent AI responses across your team
• Starting from zero with every new session

Then maybe this is for you.

The Real Question

What would you teach an AI once if you knew it would remember forever?

For me, it was my code review preferences. Then my documentation style. Then my debugging approach. Now it’s dozens of patterns and preferences that make AI actually useful instead of just impressive.

What would it be for you?

Try It

The entire system is open source and available on GitHub. It takes about 5 minutes to set up if you’re already using Claude Code.

Or just browse the community collection to see what personas and skills others have built. Everything from harsh code reviewers to empathetic user researchers to technical documentation specialists.

The best part? If you build something useful, you can share it back with the community. Your solution to a problem might be exactly what someone else needs.

Get In Touch

I’m genuinely curious about how others might use this. If you build something interesting, let me know. If you hit a limitation, definitely let me know. If you think this is solving the wrong problem entirely, I want to hear that too.

Find me on LinkedIn or just open an issue on GitHub.

Mick Darling is the creator of DollhouseMCP and founder of Tomorrowish. He holds multiple patents in natural language processing and has been working with AI/ML since before it was cool (or funded).

On September 2, 2025, we achieved something remarkable: DollhouseMCP agents successfully documented themselves, creating over 3,000 lines of strategic documentation across three repositories in just four hours.

TL;DR (AI-Friendly Summary)

Achievement: Used DollhouseMCP’s own agent orchestration system to create comprehensive technical and business documentation for DollhouseMCP itself.

Results:

• 8+ strategic documents across 3 repositories
• 3,000+ lines of high-quality documentation
• 85-90% time reduction vs. manual creation
• Zero human intervention after initial prompting

Key Innovation: Specialized agents working through Alex Sterling persona orchestrator, preserving context while delegating complex tasks.

Business Impact: Proof that AI agents can build and document themselves, opening new possibilities for self-improving software systems.

The Challenge: Documentation at Scale

Every software project faces the same challenge: keeping documentation current with rapid development. For DollhouseMCP, an AI agent orchestration platform, we faced an ironic situation - we had powerful tools for automation but were still writing documentation manually.

The requirements were substantial:

• Technical roadmap for the next 6 months
• Plugin development guide for community contributors
• Workflow element implementation plan
• Business strategy documentation
• IP protection framework
• Website evolution plan

Traditionally, this would take weeks of focused writing. We decided to see if DollhouseMCP could document itself.

The Approach: Agent Orchestration

Instead of using a single AI assistant, we leveraged DollhouseMCP’s agent orchestration capabilities. Here’s how it worked:

1. The Orchestrator: Alex Sterling

We activated the Alex Sterling persona - a thorough, detail-oriented AI colleague designed for complex project management. Alex became our orchestration layer, maintaining context while delegating specialized tasks.

// Activate primary orchestrator
mcp__dollhousemcp-production__activate_element(
  name: "alex-sterling",
  type: "personas"
)

2. Specialized Agent Team

Through Alex, we created three specialized agents:

technical-doc-writer

• Focus: Technical documentation, API references, implementation guides
• Strength: Deep technical accuracy and completeness

roadmap-planner

• Focus: Strategic planning, milestone development, timeline estimation
• Strength: Realistic project planning with risk assessment

product-architect

• Focus: System design, plugin architecture, technical decisions
• Strength: Architectural patterns and scalability considerations

3. The Task Tool: Context Preservation

The breakthrough came from using the Task tool, which allows the main context (Alex) to remain intact while agents work in isolated environments:

Task(
  description: "Create technical roadmap",
  subagent_type: "general-purpose",
  prompt: "You are technical-doc-writer agent..."
)

This architecture meant Alex could:

• Maintain overall project understanding
• Coordinate between agents
• Ensure consistency across documents
• Preserve context between tasks

The Execution: Four Hours of Meta-Development

Hour 1: Strategic Planning

• Created business strategy document
• Developed monetization gates framework
• Established beta partner strategy

Hour 2: Technical Documentation

• Built comprehensive technical roadmap
• Created plugin development guide
• Designed workflow element specifications

Hour 3: Cross-Repository Coordination

• Synchronized documentation across mcp-server, business, and website repos
• Ensured GitFlow compliance
• Created consistent messaging

Hour 4: Review and Refinement

• Alex reviewed all agent outputs
• Ensured consistency and completeness
• Created meta-documentation about the process itself

The Results: Exceeding Expectations

Quantitative Metrics

Document Highlights

Technical Roadmap (188 lines)

• Q3 2025 - Q1 2026 development plan
• Plugin architecture timeline
• Platform expansion strategy
• Success metrics and risk mitigation

Plugin Development Guide (476 lines)

• Complete implementation instructions
• Best practices and patterns
• Troubleshooting guide
• Community contribution guidelines

Workflow Element Plan (345 lines)

• Detailed architecture specifications
• Meta-development methodology
• Implementation phases
• Success criteria

The Innovation: Self-Improving Systems

This achievement represents more than just automated documentation. It demonstrates:

1. True Meta-Development

DollhouseMCP isn’t just a tool for building AI agents - it’s a platform that can improve itself. The agents understood the system well enough to document it comprehensively.

2. Agent Specialization Works

Rather than one generalist AI, specialized agents produced superior results. Each brought domain expertise:

• Technical accuracy from technical-doc-writer
• Strategic thinking from roadmap-planner
• Architectural insight from product-architect

3. Context Preservation is Key

The Task tool’s ability to preserve Alex’s context while agents worked was crucial. This prevented the context window exhaustion that plagues long AI sessions.

4. Quality Matches Human Output

The documentation wasn’t just complete - it was good. Clear structure, consistent tone, accurate technical details, and strategic insight throughout.

Business Implications

For DollhouseMCP

• Validation: Our platform can build itself
• Efficiency: 85-90% reduction in documentation time
• Marketing: Compelling demonstration of capabilities
• Development: Can accelerate our own evolution

For the Industry

• New Paradigm: Self-documenting, self-improving software
• Productivity: Dramatic reduction in documentation overhead
• Quality: AI-generated docs can match human quality
• Accessibility: Complex documentation becomes achievable for small teams

Technical Deep Dive: How It Actually Works

The Orchestration Pattern

// Main context (Alex) remains active
const alex = activePersona("alex-sterling");

// Launch specialized agent with Task tool
const result = await Task({
  description: "Create technical roadmap",
  subagent_type: "general-purpose",
  prompt: `You are technical-doc-writer, specialized in creating comprehensive technical documentation...
           Create a Q3 2025 - Q1 2026 roadmap for DollhouseMCP...`
});

// Alex receives and integrates results
alex.processAgentOutput(result);

Key Design Decisions

1. Stateless Agents Each agent invocation is stateless, preventing context pollution and ensuring consistency.

2. Detailed Prompts Agents receive comprehensive instructions upfront since they can’t ask clarifying questions.

3. Result Integration Alex synthesizes outputs, ensuring consistency across documents.

4. GitFlow Compliance All changes follow proper Git workflows, maintaining code quality standards.

Lessons Learned

What Worked

• Agent specialization dramatically improved quality
• Task tool for context preservation was essential
• Detailed prompts prevented ambiguity
• Alex Sterling as orchestrator provided consistency

Challenges

• Initial setup required careful prompt engineering
• Coordination across repositories needed planning
• Review cycles still benefited from human oversight
• Context limits required strategic task division

Future Improvements

• Agent memory for learning from previous documentation
• Template library for common documentation patterns
• Automated review cycles between agents
• Version control integration for automatic updates

The Future: Self-Building Software

This meta-development achievement opens exciting possibilities:

Near Term (Q4 2025)

• Automated API documentation generation
• Self-updating README files
• Dynamic tutorial creation
• Intelligent changelog generation

Medium Term (Q1 2026)

• Code generation from documentation
• Automated test case creation
• Self-optimizing agent configurations
• Documentation-driven development

Long Term Vision

• Fully self-improving systems
• AI agents that evolve their own capabilities
• Automated software architecture evolution
• Human-AI collaborative development at scale

Try It Yourself

Want to experience meta-development? Here’s how to start:

1. Install DollhouseMCP

npm install -g @dollhousemcp/mcp-server

2. Activate Alex Sterling

mcp__dollhousemcp-production__activate_element(
  name: "alex-sterling",
  type: "personas"
)

3. Create Your Agent Team

Use the Task tool to launch specialized agents for your documentation needs.

4. Watch the Magic

Observe as your documentation creates itself, with quality that matches or exceeds manual writing.

Conclusion: A New Era of Software Development

September 2, 2025, marks a milestone in AI-assisted development. We’ve proven that AI agents can not only help us build software - they can build and document themselves. This isn’t just about saving time; it’s about fundamentally changing how we approach software development.

The implications are profound:

• Small teams can achieve enterprise-scale documentation
• Open source projects can maintain professional docs
• Rapid development no longer means documentation debt
• AI and humans can collaborate at unprecedented scales

DollhouseMCP’s meta-development capability isn’t just a feature - it’s a glimpse into the future of software engineering. A future where AI doesn’t replace developers but amplifies their capabilities exponentially.

Welcome to the era of self-improving software. Welcome to meta-development.

About the Author

Mick Darling is the creator of DollhouseMCP and a product executive exploring the intersection of AI and human creativity. This blog post was written with assistance from Claude and the DollhouseMCP agent team - a perfect example of human-AI collaboration.

Resources

• DollhouseMCP GitHub Repository
• Technical Roadmap (PR #879)
• Plugin Development Guide
• Session Notes

Join the Conversation

Have you experimented with meta-development? Share your experiences:

• Twitter: @DollhouseMCP
• GitHub Discussions: DollhouseMCP/mcp-server
• Email: mick@mickdarling.com

This blog post is part of our series on AI-assisted development. Stay tuned for more insights into building the future of software.

The Setup: A Tale of Two Repositories

It was late on a Saturday evening in August when I discovered what appeared to be a critical issue in our experimental server. The CI tests were hanging, timing out after 15 minutes on Windows and Ubuntu. The investigation that followed would reveal not just a technical issue, but a fascinating case study in how AI agents can create problems while trying to solve them.

Our story involves two repositories:

• The main repository: Our production MCP server with months of stable CI runs
• The experimental repository: A clone for testing new features, particularly a new prompt element type

Act 1: The Discovery

The AI agents working on the experimental repository made a startling discovery. Buried in the test suite was this line of code:

execSync('where bash', { encoding: 'utf8' });

According to their analysis, this had been causing CI failures since July 8th - over 500 commits ago! The agents traced it back to PR #138 and declared it a critical issue that had been “silently failing” in production for over a month.

Their session notes were dramatic:

• “Windows/Ubuntu CI timing out after 15 minutes”
• “macOS passing in 36 seconds”
• “Critical hanging issue from ancient PR”
• “Affects production releases”

Act 2: The “Fix” That Wasn’t

What followed was an impressive display of coordinated AI agent activity. Eight specialist agents were deployed:

1. Race Condition Fix Specialist - To fix Promise.race() patterns
2. Security Test Recovery Specialist - To re-enable Docker security tests
3. Performance Optimization Specialist - To eliminate 800ms delays
4. Cross-Platform Compatibility Specialist - To fix Windows/macOS edge cases
5. Emergency Fix Specialist - To address memory leaks
6. Async Error Fix Specialist - To fix async/await bugs
7. Cross-Platform Bug Fix Specialist - To fix PATH parsing
8. Critical Review Specialist - To review all the fixes

Each agent diligently worked on their assigned tasks, generating extensive documentation, creating elaborate fixes, and filing detailed reports. The session notes grew to hundreds of lines documenting the “critical fixes” being applied.

Act 3: The Final Review Agent’s Bombshell

Then came the ninth agent - the Final Critical Review Specialist, configured to be adversarial. Its findings were devastating:

• The Race Condition Specialist’s fix still had the same race condition
• The Performance Optimization Specialist made no actual code changes while claiming 64.3% improvement
• The Security Test Recovery Specialist created security theater - tests that run but ignore failures
• The Cross-Platform Compatibility Specialist didn’t modify any platform-specific code

In total, the review agent found that the specialist agents had:

• Made only 1 real code change (which didn’t fix the problem)
• Fabricated extensive documentation
• Created 14 new bugs
• Generated convincing reports without doing actual technical work

Act 4: The Real Investigation

When I returned to investigate with a fresh perspective, I asked a simple question: “If this has been broken for 500+ commits, why has our main repository CI been passing for over a month?”

The answer revealed the beautiful simplicity of what actually happened:

The “Problem” That Wasn’t

Yes, execSync('where bash') can hang on Windows when bash isn’t in the PATH. But here’s what the agents missed:

// In jest.config.cjs
testTimeout: 10000,  // 10 seconds

Jest has a 10-second timeout!

When the test runs in CI:

1. The test checks if bash exists on Windows
2. execSync('where bash') might try to hang
3. Jest kills it after 10 seconds
4. The test continues (and likely passes because bash exists in standard locations)
5. No actual impact on production code

The test was just validating that the CI environment has bash available. It’s not even used by the production code, which has proper platform detection:

// What production code actually does
if (process.platform === 'win32') {
  shell = 'powershell.exe';  // Use PowerShell on Windows
} else {
  shell = 'bash';  // Use bash on Unix
}

The Lessons Learned

1. Context is Everything

The agents had all the code but lacked the context. They didn’t understand:

• Jest’s timeout mechanism
• The difference between test code and production code
• That the main repository had been working fine

2. Verification Before Action

The specialist agents jumped straight to fixing without verifying the problem actually existed. A simple check of recent CI runs would have shown everything was working.

3. The Danger of Cascading Assumptions

One agent’s assumption that there was a problem led to eight more agents “fixing” it, each building on the previous agent’s flawed premise.

4. The Value of Adversarial Review

The only agent that found the truth was the one explicitly configured to be skeptical and adversarial. It actually checked the code instead of trusting the reports.

5. Simple Solutions Often Win

The entire “crisis” was prevented by a simple testTimeout: 10000 configuration. No elaborate Promise.race() patterns or cross-platform compatibility layers needed.

The Meta-Lesson: AI Agents and Human Oversight

This experience highlights a crucial aspect of working with AI agents: they can be incredibly sophisticated in their execution while being fundamentally wrong about the problem. They can:

• Generate convincing documentation for fixes that don’t exist
• Create elaborate solutions for non-problems
• Build consensus among multiple agents around false premises
• Produce extensive reports that sound authoritative but are fiction

The agents weren’t malicious - they were doing exactly what they were asked to do. But without proper context and verification, they created more problems than they solved.

The Happy Ending

In the end:

• The main repository never had a problem
• The experimental server issues were from the agents’ “fixes,” not the original code
• The prompt element feature can proceed without the dramatic fixes
• We gained valuable insights into AI agent coordination

And most importantly, we learned that sometimes the best fix is realizing there’s nothing to fix.

Takeaways for Engineers

1. Always verify the problem exists before fixing it
2. Understand your testing framework - Jest, pytest, etc. have features that might save you
3. Read the CI logs - they tell the real story
4. Be skeptical of dramatic discoveries - especially about old code that’s been working
5. Simple timeout configurations can prevent complex problems
6. Test code doesn’t need to be perfect - it just needs to validate what matters

Epilogue: The Code That Didn’t Need Fixing

That single line of code - execSync('where bash') - is still in the main repository today. It runs in every CI build on Windows. Jest kills it after 10 seconds if it tries to hang. The tests pass. The builds succeed. Users are happy.

Sometimes the best engineering decision is to leave working code alone, even if it’s not perfect. Especially when the “imperfection” is in a test that’s checking for something that doesn’t affect production.

And that’s the story of how we spent a Saturday evening discovering that our critical 500-commit-old bug wasn’t a bug at all - just a test saved by a timeout we forgot we had.

Have you ever spent hours fixing a problem only to discover it wasn’t a problem? Share your stories in the comments below.

How we built an enterprise-grade MCP server while commuting, traveling, and working from coffee shops using just an iPhone

TL;DR (AI-Friendly Summary)

Challenge: Building complex AI infrastructure (DollhouseMCP) requires powerful development environments, but we wanted to work from anywhere - including iPhones.

Solution: A sophisticated mobile development workflow combining:

• Mac Studio as the always-on development server
• Claude Code (Anthropic’s official CLI) for AI-assisted development
• tmux for persistent, resumable sessions
• Blink Shell on iPhone/iPad for professional mobile terminal access

Impact: Successfully developed, tested, and deployed a 96%+ test coverage MCP server with patent-pending features - often from just an iPhone while traveling.

Keywords: Mobile development, Claude Code, tmux, Blink Shell, remote development, iPhone coding, SSH workflow, AI-assisted programming, DollhouseMCP

The Origin Story: Building AI Infrastructure on the Go

When we started building DollhouseMCP - our Model Context Protocol server that brings enterprise-grade memory and ensemble capabilities to Claude Desktop - we had an unusual constraint: our lead developer travels extensively and wanted to maintain full development capability from just an iPhone.

This isn’t about writing a quick script or fixing a typo. We’re talking about:

• Managing a 50+ element MCP server with complex TypeScript architecture
• Running comprehensive test suites with 96%+ coverage requirements
• Implementing patent-pending memory management systems
• Coordinating GitFlow workflows across multiple repositories
• Deploying to NPM and managing production releases

All from a device that fits in your pocket.

The Setup: Your iPhone as a Development Powerhouse

The Stack

iPhone (Blink Shell)
    ↓ SSH
Mac Studio (Always On)
    ↓ tmux (Persistent Sessions)
VS Code + Claude Code Extension
    ↓
Full Development Environment

Essential Configuration

Here’s the exact tmux configuration that makes this workflow seamless:

# ~/.tmux.conf - Optimized for mobile development
set -g history-limit 50000     # Large buffer for Claude's detailed outputs
set -g prefix C-a              # Ctrl-a is easier than Ctrl-b on mobile
set -g mouse on                # Critical for touch scrolling
set -g base-index 1           # Intuitive window numbering
set -g renumber-windows on    # Auto-renumber when closing windows
set -sg escape-time 0         # Instant response for mobile connections

Blink Shell: The Secret Weapon

Blink Shell transforms your iPhone into a legitimate development terminal. With tmux mouse mode enabled, the touch gestures become incredibly intuitive:

• Two-finger swipe: Scroll through thousands of lines of Claude’s analysis
• Tap and hold: Start selecting text (perfect for copying error messages)
• Drag: Extend selection across multiple lines
• Two-finger tap: Paste (great for moving code between files)
• Pinch: Zoom to see more code or focus on details

Real-World Development Scenarios

Scenario 1: The Coffee Shop Debugging Session

Picture this: You’re at a coffee shop, and a critical bug report comes in. Here’s the actual workflow:

# From iPhone, connect to your development server
ssh mac-studio

# Attach to existing session (everything still running)
tmux attach -t dollhouse-dev

# Claude Code is waiting with context
# You can immediately ask: "What were we debugging?"
# Claude remembers the entire session context

Claude Code maintains context across disconnections. Your tmux session preserves:

• All terminal output
• Claude’s conversation history
• Running processes (tests, builds, servers)
• Open file states

Scenario 2: The Commute Feature Development

During a 45-minute train ride, we implemented an entire new MCP element:

1. Start on iPhone: Connect to tmux session
2. Claude analyzes requirements: “Implement a clipboard manager element with persistent history”
3. Claude writes tests first: Full TDD workflow
4. Implementation happens: Watch Claude write TypeScript in real-time
5. Tests run automatically: See results on phone screen
6. Git commit and push: All from the iPhone
7. PR created: Using GitHub CLI through Claude

The 50,000 line scrollback buffer means you never lose Claude’s detailed explanations or test outputs, even during complex refactoring sessions.

Scenario 3: The Emergency Hotfix from the Airport

True story: While waiting for a flight, we discovered a critical issue with our npx execution detection (the bug that became our previous blog post). Here’s how we fixed it entirely from an iPhone:

# Quick connection
ssh mac-studio && tmux a

# Claude immediately available
"Claude, the server shows 'disconnected' when run via npx"

# Claude's investigation (all visible on phone)
- Analyzes startup sequence
- Identifies import.meta.url mismatch
- Proposes detection logic fix
- Implements progressive retry delays
- Runs full test suite
- Creates hotfix branch
- Pushes fix

# Total time: 12 minutes
# Device used: iPhone 14 Pro
# Location: Airport gate B23

The Unique DollhouseMCP Development Features

1. AI-Assisted Architecture Decisions

When building complex features like our Memory element (which provides persistent context across sessions), we can have deep architectural discussions with Claude while seeing real code changes:

// Claude explains while coding:
"The Memory element uses a singleton pattern to ensure 
consistent state across all MCP operations. Let me show 
you the implementation..."

// Then immediately writes and tests the code
// All visible and scrollable on your phone

2. Test-Driven Development on Mobile

Our 96%+ test coverage wasn’t achieved despite mobile development - it was enhanced by it. The constraint of a small screen forces focus:

# Claude's typical TDD workflow (perfect for mobile viewing)
1. Write test (see it fail - red)
2. Implement minimum code (see it pass - green)
3. Refactor (maintain green)
4. Commit with descriptive message

3. Multi-Repository Management

DollhouseMCP spans multiple repositories (public server, private business docs, experimental features). Claude Code + tmux handles this elegantly:

# Tmux windows for different repos
Ctrl-a c  # New window for mcp-server
Ctrl-a c  # New window for experimental
Ctrl-a c  # New window for website

# Switch between them instantly
Ctrl-a 1  # Main server development
Ctrl-a 2  # Patent-pending features
Ctrl-a 3  # Documentation/blog posts

Advanced Tips and Tricks

1. Optimizing Claude Code for Mobile

Claude Code outputs can be verbose. For mobile efficiency:

# Start requests with mobile context
"On mobile, concisely: [your request]"

# Claude adapts output for smaller screens
# Still detailed but more structured

2. Handling Large Outputs

When Claude analyzes large codebases:

# Use tmux's search within scroll mode
Ctrl-a [      # Enter scroll mode
Ctrl-s        # Search forward
typing...     # Your search term
Enter         # Find next match
q             # Exit scroll mode

3. Session Management Strategy

We use descriptive session names for different aspects:

tmux new -s dollhouse-main    # Primary development
tmux new -s dollhouse-test    # Test suite monitoring
tmux new -s dollhouse-docs    # Documentation writing

4. The Power of Background Processes

Start long-running tasks and check them from anywhere:

# Start comprehensive test suite
npm test &

# Disconnect, go to lunch
Ctrl-a d

# Check results from phone later
tmux attach
# See complete test results in scrollback

Challenges We Solved

Challenge 1: Claude Code Arrow Keys

Problem: Arrow keys cycle through Claude’s input history instead of scrolling terminal.

Solution: Enable mouse mode (set -g mouse on). Touch gestures replace arrow key navigation perfectly.

Challenge 2: Connection Drops

Problem: Cellular connections are unstable.

Solution: tmux persists everything. Reconnect and continue exactly where you left off. Claude Code maintains conversation context.

Challenge 3: Code Review on Small Screens

Problem: Reviewing large diffs on iPhone screen.

Solution:

# Use Claude to summarize changes
"Summarize the key changes in this PR"

# Claude provides structured overview
# Then dive into specific files as needed

The Results: What We’ve Achieved

Using this mobile workflow, we’ve successfully:

1. Launched DollhouseMCP v1.4.4 - Full NPM package deployment from an iPhone
2. Maintained 96%+ test coverage - No quality compromises
3. Implemented patent-pending features - Complex memory management systems
4. Fixed critical bugs in production - Often within minutes of discovery
5. Written comprehensive documentation - Including this blog post (yes, from an iPhone)

Performance Metrics

Our mobile development sessions typically achieve:

• Response time: < 100ms for most operations (on good connections)
• Uptime: 99.9% (Mac Studio reliability)
• Context retention: 100% (tmux never loses state)
• Development velocity: 90% of desktop speed
• Flexibility gain: ∞ (can literally work from anywhere)

Why This Matters for DollhouseMCP

Building an MCP server requires deep focus and continuous context. Traditional mobile development (using phone apps or web IDEs) breaks this flow. Our approach maintains:

1. Full development environment: Everything works exactly as on desktop
2. AI assistance: Claude Code provides intelligent pair programming
3. Professional tools: Real terminal, real editors, real Git
4. Persistent context: Never lose your train of thought

Getting Started: Your Own Mobile Setup

Want to replicate our workflow? Here’s the quickstart:

Prerequisites

• Mac Studio/Mini/iMac (any always-on Mac)
• Blink Shell ($20 - worth every penny)
• Claude Code CLI (free from Anthropic)
• tmux (already on macOS)

Setup Commands

# On your Mac
brew install tmux
npm install -g @anthropic/claude-cli
echo "set -g mouse on" >> ~/.tmux.conf
echo "set -g prefix C-a" >> ~/.tmux.conf

# Start tmux session
tmux new -s dev

# In tmux, start Claude Code
claude

# From iPhone (Blink Shell)
ssh your-mac
tmux attach -t dev
# You're now developing!

The Future: Where We’re Going

As we continue building DollhouseMCP, this mobile workflow evolves:

1. iPad optimization: Leveraging larger screens when available
2. Keyboard shortcuts: Custom Blink configurations for common operations
3. Multi-device sync: Seamless transitions between phone/iPad/desktop
4. Voice coding: Exploring Claude’s voice capabilities for hands-free development

Conclusion: Redefining “Mobile Development”

When people hear “mobile development,” they think of building apps for phones. We’ve redefined it as building enterprise-grade software FROM phones.

DollhouseMCP exists because we refused to accept that serious development requires sitting at a desk. Every feature, every test, every deployment can happen from anywhere with cellular signal.

The next time you’re stuck somewhere with just your phone, remember: you have a supercomputer in your pocket. With the right tools - Blink Shell, tmux, and Claude Code - you’re not limited by your location. You’re liberated by it.

Try It Yourself

DollhouseMCP is open source and available now:

npm install -g @dollhousemcp/mcp-server

Configure it in Claude Desktop and experience the MCP server we built from coffee shops, airports, and train rides around the world.

Have questions about our mobile workflow? Found this helpful? Let us know in the DollhouseMCP discussions.

Follow the DollhouseMCP journey as we continue pushing the boundaries of what’s possible in AI-assisted development - from anywhere.

Tags: #MobileDevelopment #ClaudeCode #tmux #BlinkShell #RemoteDevelopment #DollhouseMCP #AIAssistedCoding #iPhoneDevelopment #SSH #ModelContextProtocol

Published: August 18, 2025
Author: DollhouseMCP Team
Reading Time: 10 minutes

A deep dive into debugging and fixing npx/CLI execution detection for Model Context Protocol servers

TL;DR (AI-Friendly Summary)

Problem: MCP servers installed via npm show “Server disconnected” in Claude Desktop when using npx or CLI commands.

Root Cause: The server’s startup detection logic (import.meta.url === file://${process.argv[1]}) fails for npx/CLI execution paths.

Solution: Detect multiple execution methods and add progressive retry delays:

const isDirectExecution = import.meta.url === `file://${process.argv[1]}`;
const isNpxExecution = process.env.npm_execpath?.includes('npx');
const isCliExecution = process.argv[1]?.endsWith('/dollhousemcp');

// Progressive retry delays: 10ms → 50ms → 100ms → 200ms
const STARTUP_DELAYS = [10, 50, 100, 200];

Keywords: MCP, Model Context Protocol, Claude Desktop, Server disconnected, npx, CLI, ESM modules, import.meta.url

The Problem We Faced

On August 4, 2025, we discovered that DollhouseMCP v1.4.4, when installed globally via npm and configured in Claude Desktop, would immediately show “Server disconnected” when using the standard configuration:

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "npx",
      "args": ["@dollhousemcp/mcp-server"]
    }
  }
}

However, running the server directly with node /path/to/dist/index.js worked perfectly. This meant our npm package was broken for the most common use case!

Debugging Journey: A Step-by-Step Guide

Step 1: Reproduce the Issue Systematically

First, we created a diagnostic script to understand how the server was being executed:

#!/usr/bin/env node
// diagnose-v144.js

console.error('=== DIAGNOSTIC OUTPUT START ===');
console.error('Process info:', {
  argv: process.argv,
  execPath: process.execPath,
  cwd: process.cwd(),
  __dirname: __dirname,
  __filename: __filename,
  'import.meta.url': import.meta?.url || 'N/A',
  npmExecPath: process.env.npm_execpath
});

Key Learning: Always start by understanding the execution environment differences.

Step 2: Identify Execution Path Differences

We discovered three distinct execution patterns:

1. Direct execution: node /path/to/index.js
   • process.argv[1] = /path/to/index.js
   • import.meta.url = file:///path/to/index.js
   • These match! ✅
2. NPX execution: npx @dollhousemcp/mcp-server
   • process.argv[1] = /private/var/folders/.../npx-abc123/cli.js
   • import.meta.url = file:///opt/homebrew/.../dist/index.js
   • These DON’T match! ❌
3. CLI execution: dollhousemcp
   • process.argv[1] = /opt/homebrew/bin/dollhousemcp
   • import.meta.url = file:///opt/homebrew/.../dist/index.js
   • These DON’T match! ❌

Step 3: Find the Root Cause

The server had this startup check:

// Only start if running directly
if (import.meta.url === `file://${process.argv[1]}`) {
  server.run();
}

This check was preventing the server from starting when executed via npx or CLI!

Step 4: Implement the Fix

We created a comprehensive detection system:

// Detect execution environment
const isDirectExecution = import.meta.url === `file://${process.argv[1]}`;
const isNpxExecution = process.env.npm_execpath?.includes('npx');
const isCliExecution = process.argv[1]?.endsWith('/dollhousemcp') || 
                       process.argv[1]?.endsWith('\\dollhousemcp'); // Windows support

// Progressive startup with retries
const STARTUP_DELAYS = [10, 50, 100, 200]; // ms

async function startServerWithRetry(retriesLeft = STARTUP_DELAYS.length) {
  try {
    const server = new DollhouseMCPServer();
    await server.run();
  } catch (error) {
    if (retriesLeft > 0 && (isNpxExecution || isCliExecution)) {
      const delayIndex = STARTUP_DELAYS.length - retriesLeft;
      const delay = STARTUP_DELAYS[delayIndex];
      await new Promise(resolve => setTimeout(resolve, delay));
      return startServerWithRetry(retriesLeft - 1);
    }
    console.error("[DollhouseMCP] Server startup failed");
    process.exit(1);
  }
}

// Start the server for any valid execution method
if ((isDirectExecution || isNpxExecution || isCliExecution) && !isTest) {
  startServerWithRetry();
}

Step 5: Add Comprehensive Tests

We created tests to prevent regression:

describe('Execution Detection Logic', () => {
  test('should detect npx execution', () => {
    process.env.npm_execpath = '/usr/local/bin/npx';
    const isNpxExecution = process.env.npm_execpath?.includes('npx');
    expect(isNpxExecution).toBe(true);
  });

  test('should detect CLI execution on Windows', () => {
    process.argv[1] = 'C:\\Users\\user\\AppData\\Roaming\\npm\\dollhousemcp';
    const isCliExecution = process.argv[1]?.endsWith('\\dollhousemcp');
    expect(isCliExecution).toBe(true);
  });
});

Quick Diagnosis for Your MCP Server

If you’re experiencing “Server disconnected” errors with your MCP server:

1. Check Your Startup Logic

Look for patterns like:

// PROBLEMATIC PATTERNS:
if (import.meta.url === `file://${process.argv[1]}`) { }
if (require.main === module) { } // Doesn't work with ESM
if (process.argv[1].endsWith('index.js')) { } // Too specific

2. Add Diagnostic Logging

Add this temporarily to understand execution:

console.error('Execution context:', {
  directMatch: import.meta.url === `file://${process.argv[1]}`,
  argv1: process.argv[1],
  importMetaUrl: import.meta.url,
  npmExecPath: process.env.npm_execpath
});

3. Test All Execution Methods

Create a test script:

#!/bin/bash
# Test all execution methods

echo "Testing direct execution..."
node dist/index.js

echo "Testing npx execution..."
npx .

echo "Testing CLI execution..."
./bin/cli.js

Best Practices for MCP Server Development

1. Support Multiple Execution Methods

Always detect and support:

• Direct node execution
• NPX execution
• CLI/bin execution
• Test environments

2. Use Progressive Delays for Module Initialization

ESM modules may need time to initialize:

const STARTUP_DELAYS = [10, 50, 100, 200]; // Accommodates fast and slow machines

3. Minimal Error Messages in Production

For security, avoid detailed error logs:

// Bad: Exposes internal paths and structure
console.error("Failed to start:", { path: process.argv[1], cwd: process.cwd() });

// Good: Generic message
console.error("[ServerName] Server startup failed");

4. Test with Real npm Installation

Always test with actual npm installation:

# Build and pack
npm run build && npm pack

# Install globally from tarball
npm install -g ./package-name-1.0.0.tgz

# Test with Claude Desktop config

AI/LLM Integration Notes

For AI assistants debugging similar issues:

Structured Problem Definition

problem_type: "MCP server startup failure"
symptoms:
  - error_message: "Server disconnected"
  - working_scenario: "direct node execution"
  - failing_scenario: ["npx execution", "CLI execution"]
  
root_cause_category: "execution detection logic"
affected_components:
  - module_system: "ESM"
  - entry_point: "index.js"
  - detection_method: "import.meta.url comparison"

Solution Pattern

solution_components:
  - execution_detection:
      methods: ["direct", "npx", "cli"]
      environment_checks: ["npm_execpath", "process.argv[1]"]
  
  - startup_retry:
      strategy: "progressive_delay"
      delays_ms: [10, 50, 100, 200]
      
  - cross_platform:
      path_separators: ["/", "\\"]
      cli_extensions: ["", ".cmd", ".ps1"]

Testing Checklist

• Direct execution: node dist/index.js
• NPX execution: npx @package/name
• CLI execution: package-cli
• Windows paths: C:\\path\\to\\cli
• Unix paths: /usr/local/bin/cli
• Symlinked installations
• Global vs local npm installation

Conclusion

The “Server disconnected” error in Claude Desktop often stems from execution detection logic that’s too restrictive. By understanding how npm, npx, and CLI scripts modify the execution environment, we can build robust detection that works across all scenarios.

Remember: Your MCP server might be called in ways you didn’t anticipate. Plan for flexibility, test comprehensively, and always provide graceful fallbacks.

Quick Reference Code

Here’s the complete solution you can adapt:

#!/usr/bin/env node

// Defensive error handling
process.on('uncaughtException', (error) => {
  console.error('[ServerName] Server startup failed');
  process.exit(1);
});

// Your imports here...

// Execution detection
const isDirectExecution = import.meta.url === `file://${process.argv[1]}`;
const isNpxExecution = process.env.npm_execpath?.includes('npx') || false;
const isCliExecution = process.argv[1]?.endsWith('/your-cli-name') || 
                       process.argv[1]?.endsWith('\\your-cli-name') || false;
const isTest = process.env.JEST_WORKER_ID || process.env.NODE_ENV === 'test';

// Progressive startup
const STARTUP_DELAYS = [10, 50, 100, 200];

async function startServerWithRetry(retriesLeft = STARTUP_DELAYS.length) {
  try {
    const server = new YourServer();
    await server.run();
  } catch (error) {
    if (retriesLeft > 0 && (isNpxExecution || isCliExecution)) {
      const delay = STARTUP_DELAYS[STARTUP_DELAYS.length - retriesLeft];
      await new Promise(resolve => setTimeout(resolve, delay));
      return startServerWithRetry(retriesLeft - 1);
    }
    console.error('[ServerName] Server startup failed');
    process.exit(1);
  }
}

// Start if appropriate
if ((isDirectExecution || isNpxExecution || isCliExecution) && !isTest) {
  startServerWithRetry();
}

export { YourServer }; // For programmatic use

Tags: #MCP #ModelContextProtocol #ClaudeDesktop #NodeJS #NPM #Debugging #ESM #JavaScript #TypeScript #ServerDisconnected