MCP in Hull Code

Hull Code reads MCP servers from the same config files as the Hull CLI, so a server you add in one is available in the other. You can manage servers in the settings UI or edit the config directly.

Where servers are storedCopy Anchor Link

Project config takes precedence over global config. Project config loads only for projects you trust.

Manage servers in settingsCopy Anchor Link

1. Click the icon in the Hull Code sidebar to open Settings.
2. Open the Agent Behaviour tab, then MCP Servers.

From there you can:

• See each server and its status: connected, failed, needs auth, needs client registration or disabled.
• Edit a server. Choose Local server (stdio transport) to set the Command, Arguments (one per line) and Environment Variables, or Remote server (SSE/HTTP transport) to set the Server URL.
• Turn a server off without deleting its configuration.
• Click Browse Marketplace to install curated servers into your project or global config. See Marketplace.

To add a server the marketplace doesn't list, add it to a config file under the mcp key.

Config formatCopy Anchor Link

{
  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-server"],
      "environment": {
        "API_KEY": "{env:MY_API_KEY}"
      }
    },
    "my-remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:MY_TOKEN}"
      }
    }
  }
}

{env:NAME} reads an environment variable, so secrets stay out of the file. For every option, see MCP in the CLI.

Windows commandsCopy Anchor Link

On Windows, run package commands through cmd:

{
  "mcp": {
    "puppeteer": {
      "type": "local",
      "command": ["cmd", "/c", "npx", "-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

On macOS and Linux, use ["npx", "-y", "@modelcontextprotocol/server-puppeteer"].

Sign in to remote serversCopy Anchor Link

If a remote server supports OAuth, Hull Code starts the sign-in flow when you connect and the server shows needs auth until you finish. Set "oauth": false on a server to turn this off, for example when you pass a token in headers.

Auto-approve toolsCopy Anchor Link

MCP tools use the same permissions as built-in tools. Each tool's permission key is the server name and tool name joined by an underscore, such as github_create_pull_request. When a tool needs approval, you can approve it for that call or save a rule to allow it from then on.

To allow tools ahead of time, add rules to your config. Wildcards work:

{
  "permission": {
    "github_create_pull_request": "allow",
    "context7_*": "allow"
  }
}

TroubleshootingCopy Anchor Link

• failed: check the command, arguments and paths, and that the server's dependencies are installed. Run hull mcp list in a terminal to see the server's status.
• needs auth: complete the OAuth sign-in for that server, or run hull mcp auth <name>. Use hull mcp debug <name> if sign-in keeps failing.
• Server is slow to start: raise its timeout (milliseconds; the default is 30000).
• Tool missing: check the server is enabled and that it actually provides the tool.