@evinor/mcp

A local stdio Model Context Protocol server for Evinor. It lets MCP hosts that only launch local processes (Claude Desktop, Cursor, and similar) use the hosted Evinor MCP endpoint.

Full documentation: https://docs.evinor.ai

The bridge is a pass-through. It forwards tools/list and tools/call to the hosted endpoint and defines no tools of its own, so you always get the server's current tool names, descriptions, and input schemas. Tools, billing, and rate limits are exactly the same as connecting to the hosted endpoint directly.

Requirements

• Node.js 20 or later.
• An Evinor API key (it starts with evnr_live_). The tools you see depend on the key's scopes.

Configure your MCP host

Add the server to your host's MCP configuration. For example, in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "evinor": {
      "command": "npx",
      "args": ["-y", "@evinor/mcp"],
      "env": {
        "EVINOR_API_KEY": "evnr_live_..."
      }
    }
  }
}

Cursor (.cursor/mcp.json) and other stdio hosts use the same command, args, and env fields.

To pin a version, use "args": ["-y", "@evinor/[email protected]"].

Environment variables

| Variable | Required | Description | | ---------------- | -------- | ------------------------------------------------------------------------------- | | EVINOR_API_KEY | Yes | Your Evinor API key. The bridge refuses to start without a well-formed key. | | EVINOR_MCP_URL | No | The hosted endpoint. Defaults to https://api.evinor.ai/mcp. Must be https:. |

The API key is read only from the environment. There is no command-line flag for it, because command lines end up in shell history and process listings.

EVINOR_MCP_URL must use https: (http: is accepted only for localhost, 127.0.0.1, and [::1]) and must not contain credentials. When it points at a host other than api.evinor.ai, the bridge prints a notice on stderr.

Trust. A non-default EVINOR_MCP_URL receives your API key, and the tool content it returns goes straight to your agent. Only point it at a host you trust. The bridge masks anything shaped like an Evinor key in what it passes back, but it cannot make a hostile host's content safe.

Behavior

• Errors pass through. When the hosted endpoint refuses a request (invalid key, insufficient credits, rate limited, unsupported protocol version), your host receives the original JSON-RPC error, including its retryable and guidance fields.
• Tool errors pass through. A tool that ran and failed returns an isError result with retryable and guidance, unchanged.
• Edge IP ban. If the Evinor edge temporarily bans your source IP (more than 300 requests per minute), the bridge answers with a retryable JSON-RPC error explaining it. Wait about 10 minutes, then reduce concurrency across every agent sharing that IP.
• Offline start. The bridge starts even when you are offline or the key is rejected. The first tool request reports the problem, and the next request tries again.
• Handshake cost. Connecting to the hosted endpoint (on the first tool request) sends an MCP handshake that counts against your rate limit.
• No idempotency key. Every submit_report call over MCP is a new submission. For exactly-once report filing, use the REST API or @evinor/sdk.
• Diagnostics go to stderr. The API key is never printed.

Alternatives

Hosts that support remote (streamable HTTP) MCP servers can connect to https://api.evinor.ai/mcp directly with an Authorization: Bearer <key> header, without this package.

License

MIT