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

# Detailed Config

> All configuration options for connecting to the Context Graph

## Hosted Server (Recommended)

The fastest way to get started. No server to run, no dependencies to install:

```json theme={null}
{
  "mcpServers": {
    "rippletide": {
      "type": "http",
      "url": "https://mcp.rippletide.com/mcp?agentId=your-agent-id"
    }
  }
}
```

This connects directly to Rippletide's hosted MCP server. All you need is an agent ID from the [Rippletide platform](https://app.rippletide.com).

### Where to put this config

| Client             | Config file location             |
| ------------------ | -------------------------------- |
| **Cursor**         | `~/.cursor/mcp.json`             |
| **Claude Desktop** | Claude Desktop settings > MCP    |
| **Claude Code**    | `.mcp.json` at your project root |

### Agent ID

Each agent ID maps to an **isolated context graph**. Memories stored under one agent ID are invisible to another. You can:

* Use **one agent per project** to keep knowledge separated
* Use **one shared agent** across projects if you want cross-project memory
* **Switch agents at runtime** using the `switch_agent` tool during a conversation

## Self-Hosted

If you need to run the MCP server yourself (e.g. for data privacy or custom backends), use the sections below to configure and deploy it.

<Info>
  Most users don't need to self-host. The hosted MCP server at `mcp.rippletide.com` is ready to use. See the [Quickstart](/docs/mcp/quickstart).
</Info>

### Configuration

Configure the server via environment variables or CLI flags. **CLI flags take priority.**

| Env Variable    | CLI Flag      | Default                 | Description                          |
| --------------- | ------------- | ----------------------- | ------------------------------------ |
| `GRAPH_API_URL` | `--api-url`   | `http://localhost:3000` | Context graph backend URL            |
| `AGENT_ID`      | `--agent-id`  | `"default"`             | Target agent's graph                 |
| `TRANSPORT`     | `--transport` | `stdio`                 | `stdio` for local, `http` for remote |
| `PORT`          | `--port`      | `8080`                  | Port for HTTP transport              |
| `HOST`          | `--host`      | `127.0.0.1`             | Bind address for HTTP transport      |
| `LOG_LEVEL`     | `--log-level` | `info`                  | `debug`, `info`, `warn`, `error`     |

### Transport Modes

There are two ways your AI client can talk to the MCP server:

**stdio**: The AI client starts the MCP server as a subprocess and communicates via stdin/stdout. This is the default for local clients like Cursor and Claude Desktop.

```json theme={null}
{
  "mcpServers": {
    "rippletide": {
      "command": "npx",
      "args": ["-y", "@rippletide/mcp"],
      "env": {
        "GRAPH_API_URL": "http://localhost:3000",
        "AGENT_ID": "your-agent-id"
      }
    }
  }
}
```

**HTTP**: The MCP server runs as a standalone service and the AI client connects over HTTP. Use this for remote or shared deployments.

```bash theme={null}
npx @rippletide/mcp --transport http --host 0.0.0.0 --port 8080 --api-url https://your-backend.com
```

### Health Check

On startup, the server pings `GET /api/graph/stats` on the backend. If unreachable, a warning is logged but the server still starts (tools will return errors until the backend is available).

### Logging

All logs are JSON-formatted and written to stderr (stdout is reserved for the MCP stdio protocol):

```bash theme={null}
LOG_LEVEL=debug npx @rippletide/mcp
```

### Deploy

#### Deploy on Railway

The MCP server includes a `railway.json` config for one-click deployment.

<Steps>
  <Step title="Create a new service">
    Point it to your repository.
  </Step>

  <Step title="Set Root Directory">
    Set to `apps/knowledge-graph/mcp-server`
  </Step>

  <Step title="Set Start Command">
    ```bash theme={null}
    node dist/index.js --transport http --host 0.0.0.0
    ```
  </Step>

  <Step title="Add environment variables">
    | Variable        | Value                          |
    | --------------- | ------------------------------ |
    | `GRAPH_API_URL` | Your context graph backend URL |
  </Step>

  <Step title="Set Target Port">
    `8080`
  </Step>
</Steps>

Once deployed, your MCP endpoint will be available at:

```
https://your-service.railway.app/mcp
```

#### Deploy on any cloud provider

The MCP server is a standard Node.js app. To deploy anywhere:

```bash theme={null}
# Build
npm install && npm run build

# Run in HTTP mode
node dist/index.js --transport http --host 0.0.0.0 --port 8080
```

Set the `GRAPH_API_URL` environment variable to point to your context graph backend.

**Requirements:**

* Node.js >= 18
* Network access to the context graph backend

### Troubleshooting

<AccordionGroup>
  <Accordion title="Connection refused">
    The context graph backend isn't running or isn't reachable at `GRAPH_API_URL`. Check the URL and network connectivity.
  </Accordion>

  <Accordion title="Tools return empty data">
    Verify that `AGENT_ID` matches an agent that has data in the graph. Use `list_entities` to check.
  </Accordion>

  <Accordion title="Can't see logs">
    All logs go to stderr (stdout is reserved for MCP stdio protocol). Use `LOG_LEVEL=debug` for verbose output.
  </Accordion>

  <Accordion title="Server starts on stdio instead of HTTP">
    Make sure `--transport http` is in the start command or `TRANSPORT=http` is set as an environment variable.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Tools & Resources" icon="wrench" href="/docs/mcp/tools">
    See what your AI assistant can do with the 7 tools and 4 resources
  </Card>

  <Card title="Self-Hosted: Deploy" icon="cloud" href="/docs/mcp/configuration#deploy">
    Deploy on Railway or any cloud provider
  </Card>
</CardGroup>