Skip to main content

Client Settings

Every MCP client needs two values to connect to Bloque:

FieldValue
URLhttps://mcp.bloque.run/mcp
AuthorizationBearer <your API key>

Claude Code​

Claude Code connects directly to the remote HTTP endpoint. You can configure it with a project-scoped .mcp.json file or with the claude mcp add command.

Option 1: .mcp.json​

Create or update .mcp.json in your project:

{
  "mcpServers": {
    "bloque": {
      "type": "http",
      "url": "https://mcp.bloque.run/mcp",
      "headers": {
        "Authorization": "Bearer ${BLOQUE_API_KEY}"
      }
    }
  }
}

Then launch Claude Code from a shell where BLOQUE_API_KEY is set.

Option 2: claude mcp add​

Add the same server from the CLI:

claude mcp add --transport http --scope project bloque https://mcp.bloque.run/mcp \
  --header 'Authorization: Bearer ${BLOQUE_API_KEY}'

Verify with claude mcp list — bloque should appear.

See the Claude Code MCP documentation for more options.

Codex​

Codex CLI and the IDE extension share the same MCP configuration. You can configure Bloque in config.toml or with the codex mcp add command.

Option 1: config.toml​

Add this to ~/.codex/config.toml, or to .codex/config.toml in a trusted project:

[mcp_servers.bloque]
url = "https://mcp.bloque.run/mcp"
bearer_token_env_var = "BLOQUE_API_KEY"

Then launch Codex from a shell where BLOQUE_API_KEY is set.

Option 2: codex mcp add​

Add the same server from the CLI:

codex mcp add bloque --url https://mcp.bloque.run/mcp --bearer-token-env-var BLOQUE_API_KEY

Verify with codex mcp list — bloque should appear.

See the Codex MCP documentation for more options.

Environment Variables​

Claude Code, Codex, and some other MCP clients read environment variables from the process that starts the client. They usually do not load .env files automatically, so make sure BLOQUE_API_KEY is available before launching the client.

Option 1: Export the key in your shell​

Add this to your shell profile, such as ~/.zshrc or ~/.bashrc:

export BLOQUE_API_KEY="your Bloque API key"

Open a new terminal, then start claude or codex from that terminal.

Option 2: Use a small .env wrapper​

If you keep the key in a project .env file:

BLOQUE_API_KEY="your Bloque API key"

Create a wrapper script such as bin/codex-with-env:

#!/usr/bin/env bash
set -euo pipefail

set -a
source .env
set +a

exec codex "$@"

Use the same pattern for Claude Code:

#!/usr/bin/env bash
set -euo pipefail

set -a
source .env
set +a

exec claude "$@"

This works best when .env contains simple shell-compatible KEY=value lines.

Option 3: Read the key from an OS secret store​

Store the key in your operating system's managed keychain, then read it at launch time. For example, with cross-keychain:

#!/usr/bin/env bash
set -euo pipefail

export BLOQUE_API_KEY="$(cross-keychain get bloque BLOQUE_API_KEY)"
exec codex "$@"

Use exec claude "$@" instead if the wrapper is for Claude Code.

Visual Studio Code​

VS Code supports native remote MCP servers over HTTP. No bridge needed.

Edit your global or workspace mcp.json (run MCP: Add Server from the Command Palette, or edit the file directly):

{
  "servers": {
    "bloque": {
      "type": "http",
      "url": "https://mcp.bloque.run/mcp",
      "headers": {
        "Authorization": "Bearer ${input:bloque-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "bloque-api-key",
      "description": "Bloque API key"
    }
  ]
}

Cursor​

  1. Open Cursor → Integrations → MCP.
  2. Choose Edit mcp.json.
  3. Add or merge the bloque entry:
{
  "mcpServers": {
    "bloque": {
      "type": "http",
      "url": "https://mcp.bloque.run/mcp",
      "headers": {
        "Authorization": "Bearer <your API key>"
      }
    }
  }
}

LM Studio​

  1. Open LM Studio → Integrations → MCP and select Edit mcp.json.
  2. Add the bloque entry inside the mcpServers object:
{
  "mcpServers": {
    "bloque": {
      "type": "http",
      "url": "https://mcp.bloque.run/mcp",
      "headers": {
        "Authorization": "Bearer <your API key>"
      }
    }
  }
}

Saving the file automatically reloads MCP servers in LM Studio.

ChatGPT​

ChatGPT supports custom MCP connectors. This requires a Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

  1. Open ChatGPT Settings → Connectors → Advanced settings and enable Developer mode.
  2. Return to Connectors and click Create.
  3. Add a custom connector with https://mcp.bloque.run/mcp as the MCP server URL and your Bloque API key as the Bearer token.

In Team, Enterprise, and Edu workspaces, an admin may need to enable developer mode or approve custom connectors before individual users can add them.

Claude Desktop​

Claude Desktop does not currently support remote MCP connectors. Use the mcp-remote bridge instead by adding the following to claude_desktop_config.json:

{
  "mcpServers": {
    "bloque": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.bloque.run/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your API key>"
      }
    }
  }
}

Config file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json