Surface docs

Troubleshooting

Fixes for the problems people hit when connecting.

Plugin installed, but no Surface tools

The plugin's key is missing or invalid, so the server never connected. Run /plugin, choose surface-ai, configure it with a new key from Settings → Developers, and restart Claude Code.

401 Missing or invalid management key

The key is wrong or revoked, or — without the plugin — SURFACE_MANAGEMENT_KEY isn't set in the shell that launched Claude Code.

Unsupported protocol version, naming 2026-07-28

The client speaks the older handshake. Update Claude Code; other clients aren't supported yet.

A literal ${env:…} is sent as the token

That's Cursor and VS Code syntax. Claude Code expands ${VAR}.

Protocol

For building your own client — the endpoint, headers, methods and status codes.

On this page

Plugin installed, but no Surface tools401 Missing or invalid management keyUnsupported protocol version, naming 2026-07-28A literal ${env:…} is sent as the token