MCP

Connect local or remote tools to Step Code through MCP (Model Context Protocol). Once a server connects, the model can call its registered tools as needed.

Connection methods

Transport	Configuration	Use case
stdio	`command`, `args`, optional `env`	Start a local tool process
Streamable HTTP	`url`	Connect to a remote MCP service

Legacy SSE transport is not supported. Plugins can also declare MCP servers; see Plugins and packages. See Migrating from other tools for importing configuration from other tools.

Add an MCP server

Confirm the local command, arguments, and dependencies, or the remote URL and authentication requirements.
Add a declaration under [mcp_servers.<name>] in ~/.stepcode/config.toml. See Configuration below for fields, and preserve other server declarations.
Complete authentication, restart Step Code, and check the connection with /mcp.

Authentication

Read Bearer tokens from the environment running Step Code:

export EXAMPLE_TOKEN="YOUR_MCP_TOKEN"
step

For OAuth services:

step mcp login <server-name>
step mcp logout <server-name>

OAuth uses dynamic client registration, PKCE, and a local callback. Tokens are stored atomically in ~/.stepcode/.credentials.json with 0600 permissions. Model-platform login and MCP authorization use separate credentials.

Viewing servers interactively

Use /mcp for server status and loaded tool counts. States include connecting, connected, and failed. Servers with enabled = false do not appear in the list. If connection fails, check the command, environment variables, endpoint reachability, and authorization. Then request a low-risk tool call and inspect its result. Connection status checks the server connection; a tool result checks the capability you intend to use.

Tool names and filtering

Names use <server>__<tool>, with invalid characters converted to underscores. enabled_tools and disabled_tools filter tools before registration. When an allowlist is set, other tools are unavailable to the model.

Configuration

Declare servers under [mcp_servers.<name>] in global ~/.stepcode/config.toml. Project-level MCP servers are overlaid from installed plugins’ mcpServers manifests.

[mcp_servers.local-tools]
command = "node"
args = ["/absolute/path/to/mcp-server.js"]
env = { LOG_LEVEL = "info" }

[mcp_servers.remote]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "EXAMPLE_TOKEN"

[mcp_servers.remote.oauth]
callback_port = 8976

Replace the paths and endpoint with your service. Choose Bearer or OAuth as required; you do not need both.

Field	Description
`command`	stdio command; choose this or `url`
`args`, `env`, `cwd`	Optional arguments, subprocess environment, and working directory
`url`	Streamable HTTP endpoint
`bearer_token_env_var`	Name of the environment variable holding a Bearer token
`http_headers`	Literal headers; avoid embedding real keys
`env_http_headers`	Environment variable names for headers; missing variables cause an error
`startup_timeout_sec`	Startup timeout, 30 seconds by default
`tool_timeout_sec`	Per-call timeout, 300 seconds by default
`enabled`	Enable the server; default `true`
`enabled_tools`, `disabled_tools`	Tool allowlist and denylist

See Configuration files for global configuration details.

Command-line management

step mcp list
step mcp list --json
step mcp get <server-name>
step mcp add remote --url https://mcp.example.com/mcp
step mcp add local-tools -- node /absolute/path/to/mcp-server.js
step mcp remove <server-name>

--url and a local command are mutually exclusive. --bearer-token-env-var is HTTP-only. --env sets stdio subprocess variables, not HTTP headers.

Security

stdio servers launch local processes; remote services receive call arguments. Returned content can also enter model context. Check the source and access scope before connecting, and disable tools you do not need. See Permissions and safety for approval rules.

Get started

Guides

Configuration

Customization

Reference

Support and updates

Connection methods

Add an MCP server

Authentication

Viewing servers interactively

Tool names and filtering

Configuration

Command-line management

Security

​Connection methods

​Add an MCP server

​Authentication

​Viewing servers interactively

​Tool names and filtering

​Configuration

​Command-line management

​Security

Connection methods

Add an MCP server

Authentication

Viewing servers interactively

Tool names and filtering

Configuration

Command-line management

Security