MCP in the CLI
Configure MCP servers for the Hull CLI and manage them with hull mcp.
The Hull CLI loads MCP servers from its config files. Once a server connects, its tools are available to the agent alongside the built-in ones. Hull Code in VS Code reads the same files.
Config files
| Scope | Path |
|---|---|
| Global | ~/.config/hull/hull.json or hull.jsonc |
| Project | hull.json or hull.jsonc in the project (Hull looks from the current directory up to the repository root), or .hull/hull.json |
Project config takes precedence over global config, and loads only for projects you trust.
Add a server
Add servers under the mcp key. The key is the server's name.
{
"mcp": {
"my-server": {
"type": "local",
"command": ["npx", "-y", "my-mcp-command"]
}
}
}Or run hull mcp add and follow the prompts.
Server options
Local servers
Local servers run on your machine as a child process and talk to Hull over stdio.
{
"mcp": {
"my-local-server": {
"type": "local",
"command": ["npx", "-y", "my-mcp-command"],
"environment": {
"API_KEY": "{env:MY_API_KEY}"
}
}
}
}| Option | Type | Required | Description |
|---|---|---|---|
type | string | Yes | "local" |
command | string array | Yes | The command and its arguments. |
environment | object | No | Environment variables for the server process. |
enabled | boolean | No | Set to false to keep the server configured but not start it. |
timeout | number | No | Milliseconds to wait for the server. Default: 30000. |
Remote servers
Remote servers are reached over HTTP or HTTPS.
{
"mcp": {
"my-remote-server": {
"type": "remote",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer {env:MY_API_KEY}"
}
}
}
}| Option | Type | Required | Description |
|---|---|---|---|
type | string | Yes | "remote" |
url | string | Yes | The server URL. |
headers | object | No | HTTP headers to send with each request. |
oauth | object or false | No | OAuth settings (clientId, clientSecret, scope, callbackPort, redirectUri), or false to turn OAuth off. |
enabled | boolean | No | Set to false to keep the server configured but not connect. |
timeout | number | No | Milliseconds to wait for the server. Default: 30000. |
Without a clientId, Hull registers itself with the server automatically when the server supports dynamic client registration.
Environment variables
Use {env:VARIABLE_NAME} anywhere in the config to read an environment variable, so tokens stay out of the file.
Commands
| Command | Description |
|---|---|
hull mcp list | List configured servers and their status (alias hull mcp ls). |
hull mcp add | Add a server interactively. |
hull mcp auth [name] | Sign in to a server that uses OAuth. hull mcp auth list shows OAuth-capable servers and their auth status. |
hull mcp logout [name] | Remove stored OAuth credentials for a server. |
hull mcp debug <name> | Debug a server's OAuth connection. |
In the interactive TUI, use /mcps to turn servers on or off for the session.
Tool permissions
MCP tools use the same permission rules as built-in tools: allow, ask or deny. A tool's permission key is the server name and tool name joined by an underscore, such as github_create_pull_request. Wildcards like github_* match every tool from a server.
{
"permission": {
"github_create_pull_request": "ask",
"context7_*": "allow"
}
}See Permissions.
Examples
Context7 (documentation search):
{
"mcp": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp"
}
}
}Figma Desktop (the Figma app's local MCP server):
{
"mcp": {
"figma": {
"type": "remote",
"url": "http://127.0.0.1:3845/mcp"
}
}
}MCP test server (useful while building your own server):
{
"mcp": {
"everything": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
}
}
}On Windows, start package commands through cmd, for example ["cmd", "/c", "npx", "-y", "@modelcontextprotocol/server-everything"].
Find servers
Browse curated servers in the Marketplace.
Every enabled server adds its tool descriptions to the context. Servers with many tools can use a lot of it, so enable only the ones you need.