Skip to main content

​
Overview

Custom MCP (Model Context Protocol) servers extend what coding agents can do by giving them access to external tools and data sources. Define them in the Blocks dashboard using a JSON configuration object, and reference global environment variables to inject secrets at runtime. Configure custom MCP servers at Dashboard → Settings → MCP Servers. MCP servers are workspace-wide and can be enabled or disabled per agent.

​
Configuration format

Each MCP server is defined as a JSON object: 
{
  "command": "npx",
  "args": ["-y", "@my-org/my-mcp-server"],
  "env": {
    "API_KEY": "${env:MY_API_KEY}",
    "BASE_URL": "${env:MY_SERVICE_URL}"
  }
}
FieldRequiredDescription
commandYesThe executable to run (e.g., npx, node, python)
argsNoArray of arguments passed to the command
envNoEnvironment variables to set for the server process

​
Referencing environment variables

Use ${env:VARIABLE_NAME} in env values to inject global environment variables at runtime. Blocks resolves these before starting the MCP server, so secrets are never hardcoded in the configuration. The create page includes a dropdown above the JSON editor listing your global environment variables — select one to copy its template string.
Only global environment variables can be referenced. Repository-scoped variables are not available here. See Environment Variables to create them.

​
Adding a custom MCP server

  1. Go to Dashboard → Settings → MCP Servers
  2. Click Add MCP Server
  3. Enter a name for the server
  4. Paste your JSON configuration into the editor
  5. Click Save

​
Example configurations

​
Internal tool with authentication

{
  "command": "node",
  "args": ["/usr/local/bin/my-internal-tool"],
  "env": {
    "AUTH_TOKEN": "${env:INTERNAL_TOOL_TOKEN}",
    "API_BASE": "${env:INTERNAL_TOOL_URL}"
  }
}

​
Python-based MCP server

{
  "command": "python",
  "args": ["-m", "my_mcp_package"],
  "env": {
    "SECRET_KEY": "${env:MY_SECRET_KEY}"
  }
}