1

troubleshooting

Jonathan Miller edited this page 2026-05-20 01:25:22 +00:00

Table of Contents

• Troubleshooting
• Table of Contents
• Connection Issues
• "Failed to connect" to the target API
• TLS/SSL certificate errors
• Authentication failures (401/403)
• Wrong connection used
• Build Issues
• npm run build fails with TypeScript errors
• Import errors with ES modules
• npm run setup hangs or crashes
• Configuration Issues
• "Failed to load config" error
• Config file permissions error
• Tool Execution Issues
• Tool returns "Internal error"
• Tool returns empty or unexpected results
• Zod validation errors
• Claude Code Integration Issues
• MCP server not loading in Claude Code
• MCP server crashes on startup
• Diagnostic Tools
• Test API connectivity
• Debug MCP communication
• Validate config file
• Related

← Home

Troubleshooting

Common issues when developing and deploying MCP servers built from the Template-MCP template.

---

Table of Contents

• Connection Issues
• Build Issues
• Configuration Issues
• Tool Execution Issues
• Claude Code Integration Issues
• Diagnostic Tools

---

Connection Issues

"Failed to connect" to the target API

Symptom:

Error: connect ECONNREFUSED 127.0.0.1:443

Fix:

1. Verify the API URL in your config file (~/.<project>.json):

   cat ~/.<project>.json | jq '.connections'
   

2. Test the API is reachable:

   curl -I https://api.example.com/health
   

3. Check for firewall or VPN issues blocking outbound connections

---

TLS/SSL certificate errors

Symptom:

Error: self-signed certificate in certificate chain

Fix: For self-signed certificates, set "insecure": true in the connection config:

{
  "connections": {
    "staging": {
      "baseUrl": "https://staging.example.com",
      "apiKey": "key",
      "insecure": true
    }
  }
}

The ApiClient uses node:https with rejectUnauthorized: false when insecure mode is enabled.

---

Authentication failures (401/403)

Symptom:

Error: 401 Unauthorized

Fix:

1. Verify the API key/token in the connection config
2. Check if the token has expired
3. Verify the token has the required scopes/permissions for the endpoint
4. Test the token directly:

   curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/test
   

---

Wrong connection used

Symptom: Tool returns data from the wrong environment (e.g., production instead of staging).

Fix:

1. Pass the connection parameter explicitly in the tool call
2. Check which connection is the default:

   cat ~/.<project>.json | jq '.defaultConnection'
   

3. Update defaultConnection in the config if needed

---

Build Issues

npm run build fails with TypeScript errors

Symptom:

error TS2304: Cannot find name 'z'.

Fix:

1. Install dependencies:

   npm install
   

2. Verify TypeScript version:

   npx tsc --version   # Needs 5.0+
   

3. Check tsconfig.json has correct settings:

   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "Node16",
       "moduleResolution": "Node16",
       "strict": true
     }
   }
   

---

Import errors with ES modules

Symptom:

SyntaxError: Cannot use import statement outside a module

Fix:

1. Verify "type": "module" is in package.json
2. Use .mjs extension for setup scripts or add "type": "module"
3. Use import/export syntax, not require/module.exports

---

npm run setup hangs or crashes

Symptom: The setup wizard does not prompt for input.

Fix:

1. Run the setup script directly:

   node scripts/setup.mjs
   

2. Check Node.js version (20+ required for readline/promises)
3. Ensure the terminal supports interactive input (not a pipe)

---

Configuration Issues

"Failed to load config" error

Symptom:

Error: Failed to load config from ~/.my-mcp.json

Fix:

1. Run the setup wizard: npm run setup
2. Or create the config manually:

   cat > ~/.<project>.json << 'EOF'
   {
     "defaultConnection": "default",
     "connections": {
       "default": {
         "baseUrl": "https://api.example.com",
         "apiKey": "your-key"
       }
     }
   }
   EOF
   

---

Config file permissions error

Symptom:

Error: EACCES: permission denied, open '/home/user/.my-mcp.json'

Fix:

chmod 600 ~/.<project>.json

The config file should be readable only by the owner since it contains API credentials.

---

Tool Execution Issues

Tool returns "Internal error"

Symptom: Claude reports "Internal error occurred" when calling a tool.

Fix:

1. Check the MCP server logs for the actual error
2. Run the server manually to see stderr output:

   node dist/index.js 2> /tmp/mcp-debug.log
   

3. Common causes:
   • API endpoint URL mismatch
   • Missing required parameters
   • JSON parsing error on API response

---

Tool returns empty or unexpected results

Symptom: Tool executes but returns no data or wrong data.

Fix:

1. Test the underlying API endpoint directly with curl
2. Check pagination -- the tool may be returning only the first page
3. Verify the Zod schema matches the expected input format
4. Check formatResponse() for response parsing issues

---

Zod validation errors

Symptom:

ZodError: Required at "id"

Cause: A required parameter was not provided in the tool call.

Fix:

1. Check the tool's Zod schema -- is the parameter correctly marked as .optional()?
2. Verify the .describe() text clearly explains the parameter
3. Make parameters optional with defaults where appropriate

---

Claude Code Integration Issues

MCP server not loading in Claude Code

Symptom: Claude Code does not list the MCP server's tools.

Fix:

1. Check the server registration in .mcp.json or ~/.claude.json:

   {
     "mcpServers": {
       "my-mcp": {
         "type": "stdio",
         "command": "node",
         "args": ["/absolute/path/to/dist/index.js"]
       }
     }
   }
   

2. Verify the path is absolute, not relative
3. Ensure the project is built: npm run build
4. Restart Claude Code after config changes

---

MCP server crashes on startup

Symptom: Claude Code shows the server as failed/disconnected.

Fix:

1. Test the server manually:

   echo '{}' | node dist/index.js
   

2. Check for missing config file (run npm run setup)
3. Check for port conflicts if using HTTP transport
4. Review stderr output for crash details

---

Diagnostic Tools

Test API connectivity

# Test with curl
curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.example.com/health" | jq .

# Test through the MCP server's list_connections tool
echo '{"method":"tools/call","params":{"name":"list_connections","arguments":{}}}' | node dist/index.js

Debug MCP communication

# Run with verbose logging
DEBUG=* node dist/index.js 2> /tmp/mcp-debug.log

# Watch the log
tail -f /tmp/mcp-debug.log

Validate config file

# Check JSON syntax
node -e "console.log(JSON.parse(require('fs').readFileSync(process.env.HOME + '/.<project>.json', 'utf8')))"

# List connections
cat ~/.<project>.json | jq '.connections | keys'

---

Related

• Installation -- setup and configuration
• Development -- adding tools and building
• Configuration -- config file reference
• Architecture -- system design

---

Repo: Template-MCP · MokoStandards

Field	Value
Minimum Version	04.07.00
Platform	mcp-server
Applies To	MCP server repositories

Revision	Date	Author	Description
1.0	2026-05-19	Moko Consulting	Initial version