Set up your MCP client

This is the detailed client setup guide. Choose one transport, keep credentials out of source control, and then follow the complete section for the client you already use.

Client configuration recipes

These recipes describe the expected configuration shape. They do not by themselves prove a live connection, tool discovery, or an account read. See the compatibility matrix for the current retained evidence and unavailable routes.

Choose a transport

Choose	When it fits	Where SL_API_KEY lives	Client configuration
Local stdio	The client and a built simplelogin-mcp checkout are on the same machine.	In the environment or private client file	A command, arguments, and environment variables
Streamable HTTP	The server already runs continuously in Node.js, Docker, behind a proxy, or on another host.	On the server only	An /mcp URL and, when configured, a bearer token

Use Local stdio for the shortest local path. Use Streamable HTTP when you already operate the server as a service. A cloud client cannot reach 127.0.0.1 on your laptop; give it a deliberately reachable HTTPS endpoint instead.

Keep the two credentials separate

SL_API_KEY grants SimpleLogin account access and stays with simplelogin-mcp. MCP_AUTH_TOKEN protects the HTTP server boundary. The HTTP examples refer to the same server-token value through a client-side name, SIMPLELOGIN_MCP_BEARER_TOKEN; they never send SL_API_KEY to the client.

Prepare the server once

1. Create a dedicated SimpleLogin API key. Treat it as full account access. Keep the real value out of source control, screenshots, prompts, and support requests.

2. For local stdio, get and build the server. If you do not already have a checkout, clone it first:

   Build simplelogin-mcp

   git clone https://github.com/enthouan/simplelogin-mcp.git
   cd simplelogin-mcp
   corepack enable
   pnpm install --filter simplelogin-mcp --frozen-lockfile
   pnpm build

   Copy the absolute path to dist/index.js. If a desktop client cannot find node, use the absolute executable path reported by which node.

3. For Streamable HTTP, start the service first. Follow the Direct Node.js — Streamable HTTP guide or Docker Compose — Streamable HTTP guide. The default local endpoint is http://127.0.0.1:3000/mcp.

4. Prepare the appropriate private credential source. For stdio, follow the client section’s API-key instructions. For authenticated HTTP, enter a client-side alias with the same value as the server’s MCP_AUTH_TOKEN without echoing it or putting its value in shell history:

   Client-side HTTP bearer token

   printf "simplelogin-mcp bearer token: " >&2
   IFS= read -rs SIMPLELOGIN_MCP_BEARER_TOKEN
   printf "\n" >&2
   export SIMPLELOGIN_MCP_BEARER_TOKEN

Codex

Codex reads MCP servers from its TOML configuration and can forward an already exported API key without storing its value in that shared file.

Where to configure it: Export SL_API_KEY, then add this table to ~/.codex/config.toml.

Local stdio

~/.codex/config.toml

[mcp_servers.simplelogin]
command = "node"
args = ["/absolute/path/to/simplelogin-mcp/dist/index.js"]
default_tools_approval_mode = "writes"
env_vars = ["SL_API_KEY"]

[mcp_servers.simplelogin.env]
TRANSPORT = "stdio"

Protect the SimpleLogin API key

Export SL_API_KEY before launching Codex. env_vars forwards it to the child process without storing its value in TOML. The writes approval mode asks before tools that are not marked read-only.

Streamable HTTP

~/.codex/config.toml

[mcp_servers.simplelogin]
url = "http://127.0.0.1:3000/mcp"
bearer_token_env_var = "SIMPLELOGIN_MCP_BEARER_TOKEN"

Export SIMPLELOGIN_MCP_BEARER_TOKEN with the same value as the server’s MCP_AUTH_TOKEN. Omit bearer_token_env_var when the HTTP server does not require bearer authentication.

The SimpleLogin key stays on the server

The HTTP client never receives SL_API_KEY. When the server uses MCP_AUTH_TOKEN, the client sends a separate matching bearer value only to simplelogin-mcp.

Reload the client: Restart the Codex client, then open the MCP server list or use /mcp to confirm that simplelogin is connected.

Reference: Codex MCP documentation.

Claude Code

Claude Code expands environment variables in project-scoped .mcp.json files, so the shared file can reference a machine-specific checkout and secret without containing either value.

Where to configure it: Set SIMPLELOGIN_MCP_ROOT and SL_API_KEY in the environment that starts Claude Code, then create .mcp.json at the project root.

Local stdio

.mcp.json

{
  "mcpServers": {
    "simplelogin": {
      "type": "stdio",
      "command": "node",
      "args": ["${SIMPLELOGIN_MCP_ROOT}/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "SL_API_KEY": "${SL_API_KEY}"
      }
    }
  }
}

Protect the SimpleLogin API key

The file contains only environment-variable references and can be shared. Keep the environment source for SL_API_KEY private and out of version control.

Streamable HTTP

.mcp.json

{
  "mcpServers": {
    "simplelogin": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${SIMPLELOGIN_MCP_BEARER_TOKEN}"
      }
    }
  }
}

Export SIMPLELOGIN_MCP_BEARER_TOKEN with the same value as the server’s MCP_AUTH_TOKEN. Remove headers when the HTTP server does not require bearer authentication.

The SimpleLogin key stays on the server

The HTTP client never receives SL_API_KEY. When the server uses MCP_AUTH_TOKEN, the client sends a separate matching bearer value only to simplelogin-mcp.

Reload the client: Start a new Claude Code session, run /mcp, and confirm that simplelogin is connected. claude mcp list also reports missing environment variables.

Reference: Claude Code MCP documentation.

Claude Desktop

Until simplelogin-mcp is distributed as a desktop extension package, Claude Desktop can launch the locally built server as a developer-defined stdio process.

Where to configure it: Open Settings → Developer → Edit Config and add this entry to claude_desktop_config.json.

claude_desktop_config.json

{
  "mcpServers": {
    "simplelogin": {
      "command": "node",
      "args": ["/absolute/path/to/simplelogin-mcp/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "SL_API_KEY": "sl-your-key-here"
      }
    }
  }
}

Protect the SimpleLogin API key

This developer configuration contains the SimpleLogin API key. Keep the file private; do not paste it into an issue or support request.

Claude Desktop’s manual local-server configuration does not expose a documented custom bearer-header field, so this guide does not claim a protected Streamable HTTP setup for it.

Reload the client: Quit and reopen Claude Desktop. Open Connectors from the chat composer or Developer settings to check the server status and tools.

Reference: MCP local server guide.

VS Code

VS Code input variables can request the API key when the server first starts and store it without placing the value directly in mcp.json.

Where to configure it: Run MCP: Open User Configuration from the Command Palette and replace its contents or merge these inputs and server entries.

Local stdio

User profile mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "simplelogin-api-key",
      "description": "SimpleLogin API key",
      "password": true
    }
  ],
  "servers": {
    "simplelogin": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/simplelogin-mcp/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "SL_API_KEY": "${input:simplelogin-api-key}"
      }
    }
  }
}

Protect the SimpleLogin API key

The password input keeps the actual API key out of mcp.json. Use the user configuration unless you intentionally want to share a credential-free workspace definition.

Streamable HTTP

User profile mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "simplelogin-mcp-bearer-token",
      "description": "simplelogin-mcp bearer token",
      "password": true
    }
  ],
  "servers": {
    "simplelogin": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${input:simplelogin-mcp-bearer-token}"
      }
    }
  }
}

Remove both headers and the unused password input when the HTTP server does not require bearer authentication. These password-input examples target desktop VS Code.

The SimpleLogin key stays on the server

The HTTP client never receives SL_API_KEY. When the server uses MCP_AUTH_TOKEN, the client sends a separate matching bearer value only to simplelogin-mcp.

Reload the client: Run MCP: List Servers, select simplelogin, and start or restart it. Review the server configuration before accepting VS Code’s trust prompt.

Reference: VS Code MCP configuration reference.

OpenCode

OpenCode defines local servers under mcp.servers and can read the SimpleLogin API key from the environment instead of a tracked project file.

Where to configure it: Save this as opencode.json in the project or ~/.config/opencode/opencode.json for global use.

Local stdio

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "simplelogin": {
        "type": "local",
        "command": [
          "node",
          "/absolute/path/to/simplelogin-mcp/dist/index.js"
        ],
        "environment": {
          "TRANSPORT": "stdio",
          "SL_API_KEY": "{env:SL_API_KEY}"
        }
      }
    }
  }
}

Protect the SimpleLogin API key

Keep the environment that supplies SL_API_KEY private. Configuration guidance is not a live interoperability claim; check the compatibility matrix for current evidence.

Streamable HTTP

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "simplelogin": {
        "type": "remote",
        "url": "http://127.0.0.1:3000/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "Bearer {env:SIMPLELOGIN_MCP_BEARER_TOKEN}"
        }
      }
    }
  }
}

Export SIMPLELOGIN_MCP_BEARER_TOKEN with the same value as the server’s MCP_AUTH_TOKEN. Remove headers when the HTTP server does not require bearer authentication.

The SimpleLogin key stays on the server

The HTTP client never receives SL_API_KEY. When the server uses MCP_AUTH_TOKEN, the client sends a separate matching bearer value only to simplelogin-mcp.

Reload the client: Relaunch OpenCode and run opencode2 mcp list. OpenCode does not currently promise hot reload after direct configuration edits.

Reference: OpenCode MCP documentation.

Verify the connection safely

After the selected client reports that simplelogin is connected and has discovered its tools, use the same low-data, read-only check for either transport.

After the client discovers the server, use this low-data, read-only check:

Read-only verification prompt

Can you show me my SimpleLogin account usage?

Expected result

The expected tool is account_get_stats. Confirm that it is marked read-only before approving it. It takes no arguments and returns aggregate account counts without changing SimpleLogin. Those counts still pass through the client and its configured model.

Troubleshooting

• Use Troubleshooting for startup, configuration, authentication, and upstream API failures.
• Use Client compatibility to review current evidence, unavailable routes, and transport requirements.
• Review Security & Data before widening the HTTP network boundary.