Troubleshooting
Solutions for common issues when setting up and running the MCP stack.
MCP Server Not Connecting
Symptoms
- Claude Code reports "Server not found" or "Connection refused"
docker compose psshows the container asExited
Solutions
Check container status:
docker compose ps
docker compose logs ubuntu-mcp
Verify SSH to the server works:
ssh my-mcp-server "echo ok"
Test docker exec manually:
ssh my-mcp-server "echo '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | docker exec -i ubuntu-mcp python -m ubuntu_mcp"
Rebuild the container:
bash scripts/setup-build.sh
docker compose up -d --build ubuntu-mcp
Permission Denied Errors
Symptoms
- Claude Code says "Access denied" when trying to read a file or run a command
- The audit log shows
"result": "denied"entries
Solutions
Check the audit log for the reason:
tail -20 /var/log/mcp/ubuntu/audit.log | jq 'select(.result == "denied")'
Verify path exists in config:
cat configs/ubuntu-server.yaml | grep -A2 "path:"
Check default access:
If default_access: none and no path rule matches, access is denied. Add a rule or change the default.
Check command patterns:
Command patterns use fnmatch globbing. systemctl status nginx matches systemctl status * but NOT systemctl *.
Hot-Reload Not Working
Symptoms
- Editing a config YAML file doesn't take effect
- Changes require a container restart
Solutions
Check config file is mounted read-only:
The config must be mounted as :ro so the server can detect external changes.
Check server logs for reload messages:
docker compose logs ubuntu-mcp | grep -i reload
Check file permissions on the host:
ls -la configs/ubuntu-server.yaml
Force a reload by restarting:
docker compose restart ubuntu-mcp
Web UI Login Issues
Symptoms
- Login page says "Invalid API key"
- Login succeeds but immediately redirects back to login
Solutions
Verify the API key in .env:
grep WEBUI_API_KEY .env
The key must match exactly — no extra whitespace, no trailing newlines.
Check Web UI container logs:
docker compose logs mcp-webui
Clear browser cookies and localStorage for the Web UI domain, then try again.
Generate a new key if you suspect the key was corrupted:
bash scripts/generate-api-key.sh
# Copy output to .env
docker compose up -d --build mcp-webui
Synology Connection Failures
Symptoms
- DSM login fails at startup
- "Connection refused" or timeout
Solutions
Test DSM API connectivity from the Docker host:
curl -k "https://<SYNOLOGY_NAS_HOST>:<SYNOLOGY_NAS_PORT>/webapi/query.cgi?api=SYNO.API.Info&version=1&method=query"
Check credentials:
grep SYNOLOGY_NAS_ .env
If 2FA is enabled:
Verify SYNOLOGY_NAS_OTP_SECRET is the base32 secret (not the 6-digit code). Copy only the secret= value from your otpauth:// URL. Leave empty if 2FA is disabled.
Check DSM File Station is installed: The Synology MCP requires the File Station package to be installed on the NAS.
Obsidian Vault Not Found
Symptoms
- Obsidian MCP starts but shows "0 notes"
obsidian_list_vaultreturns empty
Solutions
Verify the vault path:
grep OBSIDIAN_VAULT_PATH .env
Check the directory exists and contains .md files:
ls /DATA/obsidian-vaults/personal/
Check the volume mount inside the container:
docker compose exec obsidian-mcp ls /data/vaults/
Verify permissions on the vault directory:
ls -la /DATA/obsidian-vaults/personal/
The Docker container user must have read access to the vault files.
GitHub Proxy Issues
Symptoms
- GitHub tools not available
- "Tool denied" in audit log
Solutions
Verify the GitHub token:
grep GITHUB_TOKEN .env
Check the token hasn't expired. GitHub fine-grained tokens have configurable expiration dates.
Check tool rules in config:
cat configs/github-mcp.yaml | grep -A3 "pattern:"
Test the proxy subprocess manually:
docker compose exec github-mcp python -c "
from mcp_proxy import ProxyServer
p = ProxyServer('/app/config.yaml')
print('Proxy config loaded')
"
Docker Socket Permission Errors
Symptoms
ubuntu_docker_psreturns "permission denied"- Docker socket errors in logs
Solutions
Check Docker socket permissions:
ls -la /var/run/docker.sock
# Should be: srw-rw---- 1 root docker
Add your user to the docker group:
sudo usermod -aG docker $USER
# Log out and back in
Check the container can access the socket:
docker compose exec ubuntu-mcp ls -la /var/run/docker.sock
Container Exits Immediately
Symptoms
docker compose psshowsRestartingorExited- Container restarts in a loop
Solutions
Check the container logs:
docker compose logs <service-name>
Common causes:
- Missing required
.envvariable (e.g.,SYNOLOGY_NAS_HOSTis empty) - Volume mount path doesn't exist
- Config YAML syntax error (run through a YAML validator)
Getting Help
If you're still stuck:
- Check the audit logs:
tail -100 /var/log/mcp/<server>/audit.log | jq . - Read the server logs:
docker compose logs <service> - Search existing issues: GitHub Issues
- Open a new issue: Use the bug report template with:
- Docker version (
docker --version) - Docker Compose version (
docker compose version) - Relevant logs (sanitized — remove credentials)
- Steps to reproduce
- Docker version (