Skip to content
LyraShield AIOpen beta

Updated

Troubleshooting & gotchas

The most common integration problems come from editor-specific configuration differences. Here is a quick reference for each known gotcha, followed by detailed answers.

Quick reference — per-editor gotchas

EditorGotcha
VS CodeRoot key is servers, not mcpServers. Every entry needs "type": "stdio".
Gemini CLIStrips env vars with KEY/TOKEN/SECRET in the name. Declare explicitly in the env block. No underscores in server name.
ZedRoot key is context_servers, not mcpServers.
OpenCodeRoot key is mcp. Env interpolation is {env:VAR}, not ${VAR}.
Kilo CodeSame as OpenCode: mcp key, {env:VAR} interpolation.
OpenAI CodexTOML format. Env key is env_vars, not env.
Cline (remote)Must set "type": "streamableHttp" explicitly. Omitting defaults to legacy SSE.

Frequently asked questions

The MCP server connects but no tools appear

This usually means the package has not yet resolved via npx or the API key is missing or invalid. Check that LYRASHIELD_API_KEY is set in the env block (not just the shell), that your key starts with lsk_, and that the package is available. See the package rollout note below.

VS Code does not show my MCP server

VS Code uses the root key "servers" (not "mcpServers") in .vscode/mcp.json. Every entry also requires a "type": "stdio" field. Check both. Using mcpServers silently fails without an error message.

Gemini CLI does not pass my API key to the server

Gemini CLI strips environment variables whose names contain KEY, TOKEN, or SECRET from subprocess environments. You must declare LYRASHIELD_API_KEY explicitly in the env block inside the server entry in ~/.gemini/settings.json. Inheriting it from the shell is not sufficient.

OpenCode or Kilo Code passes the literal string {env:VAR} instead of my key

These editors use single-brace interpolation: {env:LYRASHIELD_API_KEY}. Using ${VAR} or $VAR will result in the literal string being passed. Check your config for the correct syntax.

Zed does not recognize my MCP server config

Zed uses the root key "context_servers" — not "mcpServers". Place this key at the top level of your settings.json. The structure also differs from other editors — check the Zed setup page for the exact schema.

Cline connects but uses the wrong transport type

For the remote LyraShield endpoint, set "type": "streamableHttp" explicitly in cline_mcp_settings.json. Omitting the type defaults to legacy SSE transport, which is not compatible with the LyraShield remote endpoint.

The npx install fails with a package not found error

The @lyrashield/mcp package is published on npm. If npx -y @lyrashield/mcp fails to resolve, check that you're on Node.js 20+, that your npm registry is set to the public registry (npm config get registry), and that a corporate proxy or mirror isn't blocking scoped packages.

General debugging steps

  1. Confirm the LYRASHIELD_API_KEY environment variable is set inside the server entry's env block — not just in the shell.
  2. Verify the key starts with lsk_ and has not been accidentally truncated.
  3. Check that the root config key matches your editor's spec (mcpServers, servers, mcp, or context_servers).
  4. Try running the server manually to see raw output: LYRASHIELD_API_KEY=lsk_... npx -y @lyrashield/mcp.
  5. If the package fails to resolve, the @lyrashield/mcp package may not yet be available. Check the LyraShield changelog.