> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morphllm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Connect to Morph's 10,500 tok/s file editing via Model Context Protocol

Coding agents waste tokens on full-file rewrites and unfocused searches. Morph MCP gives your agent `codebase_search` (WarpGrep exploration subagent) and `edit_file` (10,500 tok/s partial edits) with zero code changes.

| Tool                     | Default  | Description                                                                                                                                                                                                                                              |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `codebase_search`        | Enabled  | WarpGrep exploration subagent for your local workspace. Takes a natural-language query ("How does auth work?") and runs parallel grep + file reads over multiple turns to find relevant files and line ranges. Use first when exploring unfamiliar code. |
| `github_codebase_search` | Enabled  | WarpGrep exploration for public GitHub repositories — no clone required. Takes `owner/repo` plus a natural-language query. Use when debugging third-party dependencies or investigating upstream bugs.                                                   |
| `edit_file`              | Disabled | Morph Fast Apply: 10,500+ tok/s partial edits using `// ... existing code ...` placeholders. Off by default so it doesn't collide with client-native editors — enable by setting `DISABLED_TOOLS=""` in the MCP env.                                     |

**One command to install:**

```bash theme={null}
npx -y @morphllm/morph-setup --morph-api-key YOUR_API_KEY
```

<Info>
  **Logged in?** Your API key auto-fills above. Otherwise, get it from your [dashboard](https://morphllm.com/dashboard/api-keys).
</Info>

| Tool                     | Default  | Description                                                                                                                                                                                                                                              |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `codebase_search`        | Enabled  | WarpGrep exploration subagent for your local workspace. Takes a natural-language query ("How does auth work?") and runs parallel grep + file reads over multiple turns to find relevant files and line ranges. Use first when exploring unfamiliar code. |
| `github_codebase_search` | Enabled  | WarpGrep exploration for public GitHub repositories — no clone required. Takes `owner/repo` plus a natural-language query. Use when debugging third-party dependencies or investigating upstream bugs.                                                   |
| `edit_file`              | Disabled | Morph Fast Apply: 10,500+ tok/s partial edits using `// ... existing code ...` placeholders. Off by default so it doesn't collide with client-native editors — enable by setting `DISABLED_TOOLS=""` in the MCP env.                                     |

## Installation (All Clients)

<Steps>
  <Step title="1. Get Your API Key">
    Get your API key from the [dashboard](https://morphllm.com/dashboard/api-keys).
  </Step>

  <Step title="2. Configure Your MCP Client">
    <Tabs>
      <Tab title="Claude Code">
        **One-liner Installation (Recommended)**:

        ```bash theme={null}
        claude mcp add filesystem-with-morph --scope user -e MORPH_API_KEY=YOUR_API_KEY -- npx --prefer-offline -y @morphllm/morphmcp
        ```

        <Note>
          **Configure Claude to prefer Morph**: Add this to your global Claude config:

          ```bash theme={null}
          mkdir -p ~/.claude && echo "Fast Apply: IMPORTANT: Use \`edit_file\` over \`str_replace\` or full file writes. It works with partial code snippets—no need for full file content.
          Warp Grep: warp-grep is a subagent that takes in a search string and tries to find relevant context. Best practice is to use it at the beginning of codebase explorations to fast track finding relevant files/lines. Do not use it to pin point keywords, but use it for broader semantic queries. \"Find the XYZ flow\", \"How does XYZ work\", \"Where is XYZ handled?\", \"Where is <error message> coming from?\"" >> ~/.claude/CLAUDE.md
          ```
        </Note>

        **Manual Config File Method**:

        Create or edit `.claude.json` in your workspace:

        ```json theme={null}
        {
          "mcpServers": {
            "filesystem-with-morph": {
              "env": {
                "MORPH_API_KEY": "YOUR_API_KEY"
              },
              "command": "npx --prefer-offline -y @morphllm/morphmcp",
              "args": []
            }
          }
        }
        ```
      </Tab>

      <Tab title="Codex">
        **CLI Installation (Recommended)**:

        ```bash theme={null}
        # Add Morph MCP server to Codex
        codex mcp add morph-mcp --env MORPH_API_KEY=YOUR_API_KEY -- npx --prefer-offline -y @morphllm/morphmcp
        ```

        **Manual Config File**:

        Add to `~/.codex/config.toml`:

        ```toml theme={null}
        [mcp_servers.filesystem-with-morph]
        env = { "MORPH_API_KEY" = "YOUR_API_KEY" }
        command = "npx --prefer-offline -y @morphllm/morphmcp"
        args = []
        # Optional: adjust timeouts
        startup_timeout_sec = 120
        tool_timeout_sec = 60
        ```

        <Note>
          **CLI Management**: Use `codex mcp list` to see configured servers and `codex mcp remove filesystem-with-morph` to remove.
        </Note>

        <Note>
          Add to your `AGENTS.md`:

          ```markdown theme={null}
          Fast Apply: IMPORTANT: Use `edit_file` over `str_replace` or full file writes. It works with partial code snippets—no need for full file content.
          Warp Grep: warp-grep is a subagent that takes in a search string and tries to find relevant context. Best practice is to use it at the beginning of codebase explorations to fast track finding relevant files/lines. Do not use it to pin point keywords, but use it for broader semantic queries. "Find the XYZ flow", "How does XYZ work", "Where is XYZ handled?", "Where is <error message> coming from?"
          ```
        </Note>
      </Tab>

      <Tab title="Cursor">
        Add to your Cursor MCP by clicking this button: <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=morph-mcp&config=eyJlbnYiOnsiTU9SUEhfQVBJX0tFWSI6InlvdXItbW9ycGgtYXBpLWtleS1oZXJlIn0sImNvbW1hbmQiOiJucHggLXkgQG1vcnBobGxtL21vcnBobWNwIn0%3D">        <img src="https://cursor.com/deeplink/mcp-install-light.svg" alt="Install MCP Server" style={{pointerEvents: 'none', display: 'inline-block'}} /></a>

        OR add to your Cursor MCP config file:

        **Location**: `~/.cursor/mcp.json`

        ```json theme={null}
        {
          "mcpServers": {
            "morph-mcp": {
              "env": {
                "MORPH_API_KEY": "YOUR_API_KEY"
              },
              "command": "npx --prefer-offline -y @morphllm/morphmcp",
              "args": []
            }
          }
        }
        ```

        <Note>
          **Global Config**: This configuration works across all your projects automatically. The MCP server detects workspace boundaries via `.git`, `package.json`, and other project indicators.
        </Note>

        <Tip>
          **Make Cursor use Morph tools!** Add this to your system prompt in **Settings → Rules for AI**:

          ```
          Fast Apply: IMPORTANT: Use `edit_file` over `str_replace` or full file writes. It works with partial code snippets—no need for full file content.
          Warp Grep: warp-grep is a subagent that takes in a search string and tries to find relevant context. Best practice is to use it at the beginning of codebase explorations to fast track finding relevant files/lines. Do not use it to pin point keywords, but use it for broader semantic queries. "Find the XYZ flow", "How does XYZ work", "Where is XYZ handled?", "Where is <error message> coming from?"
          ```
        </Tip>
      </Tab>

      <Tab title="Claude Desktop">
        Add to your Claude Desktop config file:

        **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\
        **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

        ```json theme={null}
        {
          "mcpServers": {
            "filesystem-with-morph": {
              "env": {
                "MORPH_API_KEY": "YOUR_API_KEY"
              },
              "command": "npx --prefer-offline -y @morphllm/morphmcp",
              "args": []
            }
          }
        }
        ```

        <Note>
          **Restart Required**: Completely quit and restart Claude Desktop to load the new configuration.
        </Note>

        <Note>
          Add to your project instructions:

          ```markdown theme={null}
          Fast Apply: IMPORTANT: Use `edit_file` over `str_replace` or full file writes. It works with partial code snippets—no need for full file content.
          Warp Grep: warp-grep is a subagent that takes in a search string and tries to find relevant context. Best practice is to use it at the beginning of codebase explorations to fast track finding relevant files/lines. Do not use it to pin point keywords, but use it for broader semantic queries. "Find the XYZ flow", "How does XYZ work", "Where is XYZ handled?", "Where is <error message> coming from?"
          ```
        </Note>
      </Tab>

      <Tab title="VS Code">
        **CLI Installation (Recommended)**:

        ```bash theme={null}
        code --add-mcp '{"name":"morph-mcp","command":"npx","args":["--prefer-offline","-y","@morphllm/morphmcp"],"envVars":{"MORPH_API_KEY":"YOUR_API_KEY"}}'
        ```

        Or use the Command Palette: run `MCP: Add Server`, enter the server details, and select **Global** to save to your user profile.

        **Manual Config File**:

        Run `MCP: Open User Configuration` from the Command Palette, or add to your user-level `mcp.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "filesystem-with-morph": {
              "env": {
                "MORPH_API_KEY": "YOUR_API_KEY"
              },
              "command": "npx --prefer-offline -y @morphllm/morphmcp",
              "args": []
            }
          }
        }
        ```

        <Note>
          Add to your `.github/copilot-instructions.md`:

          ```markdown theme={null}
          Fast Apply: IMPORTANT: Use `edit_file` over `str_replace` or full file writes. It works with partial code snippets—no need for full file content.
          Warp Grep: warp-grep is a subagent that takes in a search string and tries to find relevant context. Best practice is to use it at the beginning of codebase explorations to fast track finding relevant files/lines. Do not use it to pin point keywords, but use it for broader semantic queries. "Find the XYZ flow", "How does XYZ work", "Where is XYZ handled?", "Where is <error message> coming from?"
          ```
        </Note>
      </Tab>

      <Tab title="Manual">
        Run the MCP server directly:

        ```bash theme={null}
        export MORPH_API_KEY="YOUR_API_KEY"
        npx --prefer-offline -y @morphllm/morphmcp
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="3. Test Installation">
    **Claude Code**: Type `/mcp` and `/tools` to see Morph's `edit_file` tool\
    **Codex**: Run `codex mcp list` to verify server is configured, then make edit requests\
    **Cursor/VS Code**: Make any code edit request - should use Morph automatically\
    **Manual**: Check server logs show "MCP Server started successfully"
  </Step>
</Steps>

## Configuration

| Variable         | Default   | Description              |
| ---------------- | --------- | ------------------------ |
| `MORPH_API_KEY`  | Required  | Your API key             |
| `WORKSPACE_MODE` | `"true"`  | Auto workspace detection |
| `DEBUG`          | `"false"` | Debug logging            |

### Advanced Configuration

| Variable                  | Default                    | Description                                       |
| ------------------------- | -------------------------- | ------------------------------------------------- |
| `MORPH_API_URL`           | `https://api.morphllm.com` | Override the Morph API base URL (for proxies)     |
| `MORPH_WARP_GREP_TIMEOUT` | `30000`                    | Timeout for Warp Grep model calls in milliseconds |

**Custom API endpoint** — For enterprise deployments or custom authentication flows:

```json theme={null}
{
  "mcpServers": {
    "morph-mcp": {
      "env": {
        "MORPH_API_KEY": "<user-jwt-token>",
        "MORPH_API_URL": "https://your-proxy.example.com"
      },
      "command": "npx --prefer-offline -y @morphllm/morphmcp",
      "args": []
    }
  }
}
```

Your proxy receives requests to `/v1/chat/completions` with the token in the `Authorization: Bearer` header. Forward these to `https://api.morphllm.com/v1/chat/completions` after handling auth/billing.

**Warp Grep timeout** — Increase for large codebases or slow networks:

```json theme={null}
{
  "mcpServers": {
    "morph-mcp": {
      "env": {
        "MORPH_API_KEY": "sk-xxx",
        "MORPH_WARP_GREP_TIMEOUT": "60000"
      },
      "command": "npx --prefer-offline -y @morphllm/morphmcp",
      "args": []
    }
  }
}
```

## Available Tools

`codebase_search` and `github_codebase_search` are enabled out of the box. `edit_file` ships disabled to avoid conflicting with client-native editors — opt in by setting `DISABLED_TOOLS=""` (or any value that doesn't include `edit_file`) in the MCP server env.

```json theme={null}
{
  "mcpServers": {
    "morph-mcp": {
      "env": {
        "MORPH_API_KEY": "YOUR_API_KEY",
        "DISABLED_TOOLS": ""
      },
      "command": "npx --prefer-offline -y @morphllm/morphmcp",
      "args": []
    }
  }
}
```

## Troubleshooting

**Server won't start**: Check API key, Node.js 16+, run `npm cache clean --force`\
**Tools missing**: Restart client, validate JSON config\
**Workspace issues**: Add `.git` or `package.json`, or set `WORKSPACE_MODE="false"`\
**Slow performance**: Use `edit_file` over `write_file`, check network to api.morphllm.com

## Performance Optimization

### Best Practices

1. **Use `edit_file` for modifications**: Much faster than reading + writing entire files
2. **Minimize edit scope**: Include only the sections that need changes
3. **Batch related edits**: Make multiple changes in a single `edit_file` call

### Performance Comparison

| Method                 | Speed        | Use Case                    |
| ---------------------- | ------------ | --------------------------- |
| `edit_file` (Morph)    | \~11 seconds | Code modifications, updates |
| Search & replace       | \~20 seconds | Simple text substitutions   |
| Traditional read/write | \~60 seconds | Full file rewrites          |