MisakaNet/docs/topics/mcp-setup/index.html at main · ghzhost/MisakaNet · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>MCP Server Setup Issues — MisakaNet</title>
<meta name="description" content="Fix MCP server connection failures, path errors, and tool discovery issues for Cursor, Claude Code, and other AI tools. Search failure-recovery lessons.">
<link rel="canonical" href="https://misakanet.org/topics/mcp-setup/">
<meta property="og:title" content="MCP Server Setup Issues — MisakaNet">
<meta property="og:description" content="Fix MCP server connection failures, path errors, and tool discovery issues.">
<meta property="og:url" content="https://misakanet.org/topics/mcp-setup/">
<style>
  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #0a0f1d; color: #e2e8f0; max-width: 720px; margin: 0 auto; padding: 40px 20px; line-height: 1.6; }
  a { color: #58a6ff; }
  h1 { font-size: 24px; margin-bottom: 8px; }
  h2 { font-size: 18px; margin-top: 32px; margin-bottom: 12px; color: #c9d1d9; }
  .count { color: #8b949e; font-size: 14px; margin-bottom: 24px; }
  ul { padding-left: 20px; }
  li { margin-bottom: 8px; }
  code { background: rgba(110,118,129,0.2); padding: 2px 6px; border-radius: 4px; font-size: 14px; }
  pre { background: #161b22; padding: 16px; border-radius: 6px; overflow-x: auto; font-size: 14px; }
  .query { display: block; color: #8b949e; font-size: 13px; margin-top: 2px; }
  .cta { background: #1f6feb; color: #fff; padding: 12px 24px; border-radius: 6px; display: inline-block; margin-top: 12px; margin-bottom: 12px; text-decoration: none; }
  .back { margin-top: 32px; font-size: 13px; }
</style>
</head>
<body>
<h1>MCP Server Setup Issues</h1>
<div class="count">Fix connection failures, path errors, and tool discovery issues for Cursor, Claude Code, and other AI tools.</div>

<h2>Common Symptoms</h2>
<ul>
  <li><code>"MCP server not found"</code> or <code>"connection refused"</code></li>
  <li><code>"tools/list returns empty"</code></li>
  <li><code>"python3: command not found"</code> in MCP config</li>
  <li>MCP server starts but tools don't appear in Cursor/Claude</li>
  <li>Timeout waiting for MCP server response</li>
  <li><code>"ModuleNotFoundError: No module named 'misakanet_core'"</code></li>
</ul>

<h2>Real failure queries (from search logs)</h2>
<ul>
  <li><code>cursor mcp server not found windows</code><span class="query">— most common when the MCP binary isn't on the shell PATH for the editor</span></li>
  <li><code>mcp tools/list returns empty claude code</code><span class="query">— server runs but registered tools never load</span></li>
  <li><code>ModuleNotFoundError misakanet_core mcp config</code><span class="query">— package installed in the wrong Python environment</span></li>
  <li><code>python3 command not found mcp server</code><span class="query">— interpreter path missing from MCP config</span></li>
  <li><code>mcp server connection refused localhost</code><span class="query">— stdio transport blocked by firewall or wrong endpoint</span></li>
</ul>

<h2>Root Causes</h2>
<ul>
  <li>Python path not in system PATH (common on Windows)</li>
  <li><code>misakanet-core</code> not installed in the MCP server's Python environment</li>
  <li>MCP config points to wrong working directory</li>
  <li>Server crashes silently on import error</li>
  <li>Firewall blocks stdio transport</li>
</ul>

<h2>Search MisakaNet</h2>
<p>Your issue may already have a fix:</p>
<a href="/search/" class="cta">Search MCP setup lessons →</a>

<h2>Top Lessons</h2>
<ul>
  <li><a href="/lessons/mcp-server-direct-handler-testing/">MCP Server Testing — call the handler directly, skip stdio</a></li>
  <li><a href="/lessons/mcp-registry-readiness-requires-qa-before-promotion/">MCP registry readiness: QA before promoting to production</a></li>
  <li><a href="/lessons/lesson-17-segmentfault-mcp-standardization/">MCP — AI agent tool-calling standardization protocol</a></li>
  <li><a href="/lessons/glama-mcp-server-deploy-lessons/">Glama MCP server deployment — 10 build failures and fixes</a></li>
</ul>

<h2>Quick Fix Checklist</h2>
<pre><code># 1. Test MCP server directly
python3 scripts/mcp_server.py

# 2. Check tools/list response
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python3 scripts/mcp_server.py

# 3. Verify misakanet-core installed
pip install misakanet-core

# 4. Check Python path
which python3
python3 --version</code></pre>

<h2>If No Lesson Matches</h2>
<p>Submit a redacted failure report:</p>
<pre><code>python3 scripts/misaka_capture.py --summary "MCP setup failed: &lt;your error&gt;" --source mcp</code></pre>
<p>Or <a href="https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml">open an intake issue →</a></p>

<div class="back"><a href="/">← Back to MisakaNet</a> · <a href="/docs/mcp-quickstart.md">MCP Quickstart</a></div>
</body>
</html>