Skip to content

MCP connectivity

The MCP host cannot start entrabot

Entrabot is a local stdio server. The host must launch the executable and keep its stdin/stdout pipe open; there is no Entrabot HTTP listener.

Confirm the configured command exists:

=== "macOS or Linux"

```bash
test -x .venv/bin/entrabot-mcp && .venv/bin/python -c "from entrabot import config; print(config.__file__)"
```

=== "Windows"

```powershell
Test-Path .\.venv\Scripts\entrabot-mcp.exe
.\.venv\Scripts\python.exe -c "from entrabot import config; print(config.__file__)"
```

The printed module path must belong to the repository the host is opening. Use an absolute MCP command path when the host starts from a different working directory.

The server imports code from another worktree

Editable installs record a source path. Never run an editable install in a worktree with the parent repository's .venv; that silently points the parent environment at the worktree.

Each worktree that needs an install must have its own .venv. Verify the active target:

.venv/bin/python -c "from entrabot import config; print(config.__file__)"

If the path is wrong, recreate the affected environment in the intended repository and update the MCP command path.

Tools load, but authentication fails

Transport health and authentication health are separate:

  • A launch error, EOF, malformed JSON-RPC, or missing executable is an MCP transport problem.
  • UNAUTHENTICATED, token-exchange errors, consent errors, and Graph 401/403 responses are authentication or authorization problems.

Run the status command, then call whoami. If both work but a specific tool fails, troubleshoot that resource rather than the stdio transport.

persona-sati does not connect

persona-sati is optional; without it Entrabot runs standalone as a generic Teams tool. If you use it and its tools are missing, check how the persona-sati entry in .mcp.json reaches it:

  • Hosted (the usual case). The entry is a stdio entry whose command is the absolute path of the client launcher from your persona-sati install, and PERSONA_SATI_MCP_URL / PERSONA_SATI_MCP_TOKEN_COMMAND are set in the entrabot entry's env. The launcher and token command come from your persona-sati install's own setup documentation. .mcp.json.example in the repository root shows the shape.
  • Local development only. An sse entry with a localhost URL works only while you run persona-sati yourself on that port. Nothing listens there otherwise, and a refused local connection says nothing about whether a hosted service is up.

On macOS or Linux, run the health check:

./scripts/setup.sh --diagnose

The persona-sati MCP (optional) line never fails the run:

Result Meaning
SKIP .mcp.json is missing, unreadable, or has no persona-sati entry, so Entrabot runs standalone.
PASS A stdio launcher exists and is executable, a loopback URL accepts connections, or a non-local URL is configured (it is not contacted).
WARN A <...> placeholder was never filled in (the launcher, or PERSONA_SATI_MCP_URL / PERSONA_SATI_MCP_TOKEN_COMMAND), a launcher or token command is missing or not executable, the URL is not a valid http(s) URL, or nothing is listening at a localhost URL.

The check reports only the launcher path and the URL's scheme, host, and port. It does not print headers, tokens, or other env values, and it connects only to loopback addresses.

Claude Code receives no background Teams or email messages

Launch with the channel flag:

claude --dangerously-load-development-channels server:entrabot

The MCP server name must match .mcp.json. Without the flag, tools can still work while notifications/claude/channel is not surfaced as a new turn.

Copilot CLI and other non-channel hosts do not receive an out-of-band model turn. Their send_teams_message path auto-waits and returns sponsor replies inline instead.

The server disconnects or exits without enough diagnostics

On macOS or Linux, temporarily point the MCP command to:

scripts/entrabot-mcp-debug.sh

The wrapper:

  • Copies stderr to /tmp/entrabot-debug.log while preserving normal stderr.
  • Leaves stdout untouched for MCP JSON-RPC.
  • Contains the shipped # entrabot-self-ref-target: marker so efferent-copy discovery recognizes the wrapper as the running Entrabot executable instead of spawning a duplicate.

Inspect the log:

tail -f /tmp/entrabot-debug.log

Restore the normal .venv/bin/entrabot-mcp command after diagnosis and remove the unrotated diagnostic log:

rm -f /tmp/entrabot-debug.log

Treat the log as sensitive-adjacent even though normal Entrabot logging redacts credential-bearing values.

Optional observer discovery may be involved

Efferent-copy observer dispatch is off by default. If it is enabled in the environment, isolate it during transport diagnosis:

EFFERENT_COPY_DISABLE=1 .venv/bin/entrabot-mcp

For an MCP host, set EFFERENT_COPY_DISABLE=1 in the server environment and restart the host. If the problem persists, the optional observer path is not the cause.

Debug output corrupts the MCP connection

Stdout is the stdio JSON-RPC transport. Do not add print() diagnostics to stdout in the MCP server. Use structured logging, which writes to stderr and the rotating entrabot.log, or use the debug wrapper above.

See MCP Hosts and Transports, MCP Runtime, and Debug Wrapper Reference.