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

# MCP Integration

> Connect Claude, Cursor, LangChain, or any MCP client to Bossa.

# MCP Integration

Bossa exposes a virtual filesystem via **MCP** (Model Context Protocol). Connect Claude Desktop, Cursor, LangChain, or any MCP-compatible client to use `ls`, `read_file`, `write_file`, `grep`, `glob_search`, `edit_file`, and `delete_file`.

**MCP endpoint:** `https://bossamemory.com/mcp`

**Alternative:** If your agent harness runs tools as subprocesses (CLI-based), use the Bossa CLI instead: `bossa files ls`, `read`, `write`, `grep`, `glob`, `edit`, `delete` with `--json` or `BOSSA_CLI_JSON=1`. See [CLI Reference](CLI).

***

## Authentication

Pass your workspace API key in HTTP headers when connecting:

| Header          | Value                 |
| --------------- | --------------------- |
| `Authorization` | `Bearer YOUR_API_KEY` |
| `X-API-Key`     | `YOUR_API_KEY`        |

Both headers are supported; use at least one.

***

## Available Tools

| Tool          | Description                                                        | Read-only |
| ------------- | ------------------------------------------------------------------ | --------- |
| `ls`          | List files and directories at a path. Directories end with `/`.    | ✓         |
| `read_file`   | Return file contents with numbered lines (`1: line text`).         | ✓         |
| `write_file`  | Create or overwrite a file.                                        |           |
| `edit_file`   | Replace substring in a file. Use `replace_all` for replace-all.    |           |
| `stat`        | Return file metadata: path, size, modified, created.               | ✓         |
| `grep`        | Search file contents (literal/regex, boolean filters, pagination). | ✓         |
| `glob_search` | Find files by glob pattern (e.g. `**/*.py`).                       | ✓         |
| `delete_file` | Permanently delete a file.                                         |           |

Tools include MCP annotations (`readOnlyHint`, `destructiveHint`, etc.) so clients can skip confirmation for safe operations.

***

## Client Setup

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "mcpServers": {
    "bossa": {
      "url": "https://bossamemory.com/mcp",
      "transport": "streamable_http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}
```

Replace `YOUR_API_KEY` with your workspace API key. Restart Claude Desktop.

### Cursor

Add Bossa as an MCP server in Cursor settings. Use:

* **URL:** `https://bossamemory.com/mcp`
* **Transport:** Streamable HTTP
* **Headers:** `Authorization: Bearer YOUR_API_KEY` or `X-API-Key: YOUR_API_KEY`

### LangChain (Python)

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "bossa": {
        "url": "https://bossamemory.com/mcp",
        "transport": "streamable_http",
        "headers": {
            "X-API-Key": "YOUR_API_KEY",
            "Authorization": "Bearer YOUR_API_KEY"
        }
    }
})

tools = await client.get_tools()
# Use tools with your agent
```

### Generic MCP Client (HTTP)

The MCP endpoint uses the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/server/transports#streamable-http) transport. Any client that supports streamable HTTP + custom headers can connect.

***

## Tool Details

### `ls`

List immediate children at a path.

* **path** (optional): Directory path. Default: `/`
* Returns: One entry per line; directories end with `/`

### `read_file`

Read a file's full contents.

* **path** (required): Absolute file path
* Returns: Numbered lines (`1: line text`) or error if not found

### `write_file`

Create or overwrite a file.

* **path** (required): Absolute path
* **content** (required): Full file content

### `edit_file`

Replace the first occurrence of a string in a file.

* **path** (required): File path
* **old\_string** (required): Substring to replace
* **new\_string** (required): Replacement

### `grep`

Search file contents with flexible options.

* **pattern**: Literal or regex pattern
* **path**: Scope to subtree (default: `/`)
* **regex**: Use regex for pattern (default: false)
* **case\_sensitive**: Case-sensitive match (default: false)
* **output\_mode**: `matches` | `files_with_matches` | `count`
* **all\_of**, **any\_of**, **none\_of**: Boolean filters (same line)
* **max\_matches**, **offset**: Pagination
* **context\_before**, **context\_after**: Context lines around matches

### `glob_search`

Find files by glob pattern.

* **pattern** (required): Glob (e.g. `**/*.md`, `/docs/*.txt`)
* **path** (optional): Scope to subtree (default: `/`)

### `delete_file`

Permanently delete a file.

* **path** (required): File path

***

## Workspace Isolation

Each API key maps to one workspace. Files in workspace A are invisible to workspace B. Create multiple workspaces and keys for different apps or tenants.