Warp-mcp

Warp Terminal MCP – Integration with Alph Overview: Warp is a modern terminal that features an “Agent Mode” with AI assistance. Warp supports MCP servers as modular plugins to extend its AI agents with custom tools and data[18]. Integrating Alph with Warp means configuring Warp’s MCP client to know about Alph’s MCP server. Warp’s integration differs from Windsurf’s in a few key ways: Warp provides a GUI and a CLI to manage MCP servers, uses slightly different JSON fields for configuration, and may sync settings across machines via cloud. Alph should leverage Warp’s mechanisms (preferably the CLI) to register the Alph MCP server, ensuring it starts/stops correctly with Warp and is available to the agent. Accessing MCP Configuration in Warp Warp doesn’t use a simple static file like Windsurf; instead, it’s managed via Warp’s settings. There is a JSON representation of configured servers (as shown when adding multiple servers via the UI), but the actual storage might be internal (potentially synced to the cloud for the user). Key points: • Warp MCP UI: Users can add servers through Warp Drive > MCP Servers in the GUI or via the command palette (Open MCP Servers)[19]. In the UI, they can click “+ Add” and either fill a form (for single server) or paste a JSON snippet (for multiple)[20][21]. This suggests Warp’s config ultimately is JSON-based under the hood. • Config File Location: The documentation does not explicitly give a config file path for MCP servers. Community discussions indicate it’s not a single user-editable file; instead, warp might store it in an internal database or cloud. However, Warp log files are stored under the user’s data directories (e.g., /Library/Application Support/dev.warp.Warp-Stable/mcp on macOS)[22]. The presence of mcp logs suggests a config exists in Warp’s state. There is no official “/.warp/mcp_config.json” (unlike Claude or Windsurf). Therefore, Alph should avoid blindly creating a file. Instead, the recommended approach is to use Warp’s CLI to add the server entry. • Warp CLI Availability: Warp comes with a CLI (the warp or warp-terminal command) installed alongside the app[23][24]. Alph should detect if warp (or on Linux, warp-terminal) is in PATH. If Warp CLI is unavailable (perhaps not installed in PATH), Alph might prompt the user to add it via Warp settings or use the GUI as a fallback. Warp’s CLI help suggests an mcp subcommand. At minimum, warp mcp list is available to list configured servers[25]. Adding servers via CLI: though Warp’s official docs don’t list it under warp help mcp, multiple sources (community guides) show a command for adding servers from a JSON file: warp mcp add-server --config mcp_config.json [26]. This implies Warp CLI can consume a JSON snippet file and register those servers (similar to pasting in the UI). Alph can use this to automate setup. Specifically, Alph would generate a temporary JSON file containing the mcpServers object for Alph’s server and run warp mcp add-server --config /path/to/temp.json. Warp will then import that config. (The JSON format here is the same structure as used in the UI snippet – see below.) If for any reason this CLI approach fails (for example, if the CLI command syntax changed or requires Warp to be running), Alph should fall back to instructing the user to open Warp’s MCP settings and paste the JSON snippet manually. But assuming current Warp versions support the CLI command, this is the quickest integration path. MCP Server Schema for Warp Warp distinguishes two types of MCP server configurations, presented as CLI servers and SSE (URL) servers in documentation[20][27], but both are ultimately entries under the mcpServers JSON. The schema for each entry: • Key (server name/ID): Each server is identified by a unique name. In Warp’s UI examples, they often use Capitalized names (e.g. "GitHub" or "filesystem")[28][29]. The name can contain spaces or special characters (e.g. “Official Figma MCP (SSE)” in an example[30]), but it’s safest for Alph to use a concise alphanumeric name (since this key might be used as an identifier in CLI commands or logs). Alph might use something like "AlphServer" or "alph-tools". (Note: Warp will internally assign a stable UUID to each server, but that’s transparent to the user[31].) • command (string) – Executable for launching a local MCP server (same meaning as in Windsurf). Required for CLI-type servers[32]. e.g. "npx", "docker", or path to a script. • args (array[string]) – Required for CLI servers[33]. Arguments to pass to the command. Warp’s examples: ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"] for a Node server[29], or Docker run args for GitHub server[28]. Alph should populate this with whatever is needed to start its server. For instance, if Alph’s MCP server is an executable, command might be the path and no args; if it’s an npm module, use npx and module name; if it’s a Docker container, use docker and the run parameters. • env (object, optional) – Environment variables or headers. Warp uses one env object for both CLI and SSE servers[34][35]. For CLI servers, these keys become environment variables in the launched process. For SSE (URL) servers, Warp treats env entries as HTTP headers or auth tokens to include when connecting (the docs hint it’s for “environment variables or headers (e.g., tokens)” in the SSE context[35]). Alph can place API keys, tokens, etc., here as needed. (E.g., for an SSE server requiring a bearer token, the user might set "Authorization": "Bearer " in env – Warp likely translates that to an HTTP header.) • working_directory (string, optional) – Directory in which to run the CLI command[36]. This is unique to Warp (Claude/Windsurf don’t have it). Warp recommends always setting this if relative paths are used in command or args[37]. Alph should determine an appropriate working dir for its server. If Alph’s server command is insensitive to CWD (e.g. a globally installed package), this can be just the user’s home or left unset. If Alph’s config involves relative paths (like a script in the current project), Alph should provide a path. Possibly, Alph might default to the user’s current directory or allow a flag for working directory. Since Alph’s own AgentConfig includes cwd, Alph can pass that through to Warp. In summary, if AgentConfig.cwd is set and the server type is CLI, use that as working_directory in Warp’s config for consistency. • url (string) – For SSE/HTTP servers, this is the full URL to connect to[38]. Required for URL-type servers (if present, Warp knows this is not a local process but an external endpoint). Typically it’s an SSE stream endpoint. For example, an official remote GitHub server might use "url": "https://api.githubcopilot.com/mcp/"[39] or a local dev server could be "url": "http://localhost:4000/mcp/stream"[40]. Alph should supply the correct URL to its MCP service if using this mode. (If Alph’s integration is meant to launch a local service itself, we’d use command instead, not url.) • start_on_launch (boolean, optional) – By default, Warp auto-starts CLI servers on Warp launch (and reconnects to any SSE servers) unless told otherwise. The docs say to disable auto-start, set "start_on_launch": false in the server config[41]. Alph likely can leave this as true (or unspecified, which defaults to true). If the Alph server should not run unless explicitly started by user, Alph could set this to false. Generally, to “accelerate” integration, auto-start is convenient: as soon as Warp opens, Alph’s server will launch and be ready. JSON Insertion: If using the CLI method (warp mcp add-server --config), Alph should create a JSON file containing an object with an mcpServers key, similar to the snippet used in Warp’s docs[21]. For example, Alph might generate: { "mcpServers": { "AlphServer": { "command": "/usr/local/bin/alph-mcp",
"args": ["--stdio"],
"env": { "ALPH_API_KEY": "XYZ123" },
"working_directory": "/Users/alice/projects/myapp"
} } } This would register a server named “AlphServer” that Warp will launch by running the alph-mcp binary with --stdio (assuming Alph provides such a binary), with a provided API key, and using the specified working directory. After generating this file, Alph runs the CLI command to import it. Warp will merge this with existing config – as per docs, all servers in the snippet are added automatically[42][29]. If multiple MCP servers need adding at once, Alph can include them all under mcpServers in that temp file. But typically Alph will add just one (the Alph server). Alternate Approach: Without CLI, the user could manually paste a snippet like the above via Warp’s UI. Alph can output or log the JSON snippet for the user in that case. However, using the CLI is more automated and less error-prone. Activation and Usage in Warp Once added, the Alph server will appear in Warp’s “MCP Servers” settings list. Key integration points: • Auto-Start: If the server is a CLI type and Warp is running when added, does Warp start it immediately? The docs imply that after adding (via UI or CLI), the server is added to the list but may not start until either the user clicks “Start” or the next Warp launch. The UI offers Start/Stop controls for each server[43]. It’s safe to assume Alph’s server will not be running until explicitly started or Warp is restarted. Alph could instruct the user: “Open Warp’s MCP Servers panel and click ‘Start’ on AlphServer (if it’s not already running).” If start_on_launch remained true, then simply restarting Warp will also launch it. • Tool Availability: When running, the MCP server will register its tools and resources with Warp’s agent. The user can verify this by checking the list of tools under that server’s entry in Warp’s UI (Warp shows available tools/resources for each running server). For example, the UI might list “get_entity_state, search_entities, …” if those are tools provided by Alph’s server. Ensuring Alph’s server properly declares its tools in the MCP handshake is outside the scope of config, but important for end-to-end functionality. • Using the Tools: In Warp’s Agent Mode (triggered by pressing Cmd+K or entering the agent prompt), the user’s queries can now utilize the Alph server’s capabilities. Warp’s agent will automatically include the MCP tools as available functions. No special command-line flag is needed at runtime for the user; it’s seamlessly integrated. (For advanced use, Warp CLI’s agent run command can take an --mcp-server flag to force using a specific server[44], but typically if the server is configured and running, the agent will consider it.) • Cloud Sync Consideration: Warp accounts sync MCP server configurations across installations[31]. If the user has Warp on multiple machines logged into the same account, adding “AlphServer” on one should propagate the config to others. However, the server’s executable might not exist on the other machines. Warp notes that while configs sync, “any necessary server programs must be installed on each one.”[44]. Alph should mention this: “If you use Warp on multiple devices, the Alph server entry will sync to all of them (so you’ll see it listed), but you’ll need to ensure the Alph MCP server is installed or accessible on each machine for it to actually run.” This is particularly relevant if Alph’s server is a local binary or requires certain environment setup. Logs and Troubleshooting Warp provides robust logging and debugging support for MCP: • Logs Location: Warp saves MCP server logs to disk. This is extremely helpful for integration testing. According to docs, logs reside at: – macOS: ~/Library/Application Support/dev.warp.Warp-Stable/mcp – Windows: %LOCALAPPDATA%\warp\Warp\data\logs\mcp – Linux: ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/mcp[22]. Alph can surface this info (perhaps via a command like alph status or in documentation) so users know where to find logs. For example, if Alph’s server fails to start (maybe the command is not found, or it crashes), the user can inspect these log files. Alph might even automate a check: after adding the server and starting it, tail the log file to see if the process is running properly. • Debugging Tools: Warp’s UI has a “View Logs” button per server[45], which opens the above log. It also notes common issues: for SSE servers, treat the URL like a password (secret)[46]. For auth issues, there’s advice to clear stored tokens by deleting ~/.mcp-auth (which Warp uses to cache OAuth tokens)[47]. If Alph’s server requires authentication (say OAuth), Alph might not be involved in that (Warp would prompt the user via browser, etc., if it were like connecting to a third-party service). But since Alph’s integration likely uses direct tokens in config, the env approach should suffice. • Common Pitfalls: If the MCP server isn’t working in Warp: • Ensure the server is running. If not autostarted, user must start it. • For CLI servers, check that the command is correct and in PATH (if Warp can’t find the command, the server won’t launch – e.g., if using npx, Node.js must be installed). • If the server started but tools aren’t responding, check the log for errors or whether the server exited. • For SSE servers, ensure the URL is reachable from the machine and is an SSE endpoint. Warp might show an error if it can’t connect. • If Warp’s agent isn’t using the server’s tools when expected, try a different model in Warp. The docs mention some AI models work better with MCP servers than others[48]. This is outside Alph’s control, but the user could experiment (e.g., if using GPT-4 vs Claude in Warp, one might call tools more eagerly). • Removal or Update: If Alph needs to update the server config (say the user changes a token), the Warp CLI does not yet have an explicit update command. A workaround is to remove and re-add. Removal can be done via the UI (delete the server) or possibly by an mcp remove-server command (not documented, but warp mcp list shows IDs which might be removable via API/CLI). If not, Alph may have to instruct the user to remove via UI and then re-add via Alph. In any case, Alph should handle re-running add-server for the same name gracefully (Warp might ignore duplicate names or create another entry with a suffix). It’s ideal to check if “AlphServer” is already present (maybe using warp mcp list which lists names/IDs) and then decide to skip or update. Example: Consider Alph integrating a “Filesystem” MCP server on Warp (similar to Claude’s example). Warp’s docs show adding a local filesystem server with restricted paths[49][50]. If Alph were doing this, it would set command: "npx" and args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/alice/Desktop", "/Users/alice/Downloads"] (with those paths coming from user input about which directories to allow). It would then run the warp mcp add-server command with that JSON. Afterward, “Filesystem” appears in Warp, user can start it, and Claude (or whichever model in Warp) can now read/write files with user approval. This scenario is analogous to what Alph must do for its own server – define the right command (or URL) and parameters, add to Warp, and potentially notify the user how to start it. Finally, ensure Alph informs users of success or next steps. For Warp, upon successful addition via CLI, the command likely prints nothing if successful (or the new server’s ID). Alph can then print a confirmation like: “✅ Added MCP server AlphServer to Warp. Open Warp’s Knowledge & Collaboration > MCP Servers settings to verify. You may start the server from there or restart Warp to auto-launch it.” Additionally, mention the log file path for debugging if needed (as above). If any required detail is missing (for example, if future Warp versions require a different CLI syntax), Alph’s maintainers should check Warp’s latest docs or use warp help mcp for updates[51]. As of now, the integration steps outlined should cover the essential technical details to get Alph talking to Warp’s agent via MCP. Sources: • Warp MCP official documentation (features and JSON schema)[38][29][40] • Warp documentation on adding CLI vs SSE servers and working_directory usage[37][36] • Warp CLI usage (community example for adding server via config)[26] • Warp blog/CLI docs (notes on sync across machines and usage of MCP servers)[44] • Warp documentation on logs and troubleshooting MCP servers[45][22]