# Moose / Mcp Dev Server Documentation – TypeScript

## Included Files
1. moose/mcp-dev-server/mcp-dev-server.mdx

## MCP Server

Source: moose/mcp-dev-server/mcp-dev-server.mdx

Built-in Model Context Protocol server for AI-assisted development

# MCP Server for AI-Assisted Development

The Moose development server includes a built-in Model Context Protocol (MCP) server that enables AI agents and IDEs to interact directly with your local development infrastructure. This allows you to use natural language to query data, inspect logs, explore infrastructure, and debug your Moose project.

## What is MCP?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open protocol that standardizes how AI assistants communicate with development tools and services. Moose's MCP server exposes your local development environment—including ClickHouse, Redpanda, logs, and infrastructure state—through a set of tools that AI agents can use.

## Quick Start

The MCP server runs automatically when you start development mode:

```bash
moose dev
```

The MCP server is available at: `http://localhost:4000/mcp`

The MCP server is enabled by default. To disable it, use `moose dev --mcp=false`.

## Configure Your AI Client

Connect your AI assistant to the Moose MCP server. Most clients now support native HTTP transport for easier setup.

<Tabs.Tab>

**Setup**: Use the Claude Code CLI (easiest method)

```bash copy
claude mcp add --transport http moose-dev http://localhost:4000/mcp
```

That's it! Claude Code will automatically connect to your Moose dev server.

**Scope**: This command adds the MCP server to Claude Code's project configuration, making it available to your project when using Claude Code. Other AI clients (Cursor, Windsurf, etc.) require separate configuration - see the tabs below.

Make sure `moose dev` is running before adding the server. The CLI will verify the connection.

**Alternative**: Manual configuration at `~/.claude/config.json`

```json filename="config.json" copy
{
  "mcpServers": {
    "moose-dev": {
      "transport": "http",
      "url": "http://localhost:4000/mcp"
    }
  }
}
```

</Tabs.Tab>

<Tabs.Tab>

**Location**: `~/.codeium/windsurf/mcp_config.json`

Windsurf supports native Streamable HTTP transport:

```json filename="mcp_config.json" copy
{
  "mcpServers": {
    "moose-dev": {
      "serverUrl": "http://localhost:4000/mcp"
    }
  }
}
```

</Tabs.Tab>

<Tabs.Tab>

**Prerequisites**:
- VS Code 1.102+ (built-in MCP support)
- Or install the [Cline extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev)

**Option 1: Native HTTP Support (VS Code 1.102+)**

Add to `.vscode/settings.json` or User Settings:

```json filename=".vscode/settings.json" copy
{
  "mcp.servers": {
    "moose-dev": {
      "transport": "http",
      "url": "http://localhost:4000/mcp"
    }
  }
}
```

**Option 2: Cline Extension**

Configure in Cline's MCP settings:

```json copy
{
  "moose-dev": {
    "transport": "sse",
    "url": "http://localhost:4000/mcp"
  }
}
```

</Tabs.Tab>

<Tabs.Tab>

**Location**: `.cursor/mcp.json` (project-level) or `~/.cursor/settings/mcp.json` (global)

Cursor currently uses stdio transport. Use `mcp-remote` to bridge to HTTP servers:

```json filename=".cursor/mcp.json" copy
{
  "mcpServers": {
    "moose-dev": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:4000/mcp"
      ]
    }
  }
}
```

</Tabs.Tab>

<Tabs.Tab>

**Location**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Access via: Claude > Settings > Developer > Edit Config

```json filename="claude_desktop_config.json" copy
{
  "servers": {
    "moose-dev": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:4000/mcp"
      ]
    }
  }
}
```

The `-y` flag automatically installs `mcp-remote` if not already installed.

</Tabs.Tab>

Make sure `moose dev` is running before using the MCP tools. The AI client will connect to `http://localhost:4000/mcp`.

## Available Tools

The Moose MCP server provides five tools for interacting with your local development environment.

**Recommended workflow**: Always start with `get_infra_map` to understand project structure and locate files.

### `get_logs`

Retrieve and filter Moose development server logs for debugging and monitoring.

**What you can ask for:**
- Filter by log level (ERROR, WARN, INFO, DEBUG, TRACE)
- Limit the number of log lines returned
- Search for specific text patterns in logs

**Example prompts:**

*"Show me the last 10 ERROR logs"*

```
Showing 10 most recent log entries from /Users/user/.moose/2025-10-10-cli.log
Filters applied:
  - Level: ERROR

[2025-10-10T17:44:42Z ERROR] Foo -> Bar (worker 1): Unsupported SASL mechanism: undefined
[2025-10-10T17:44:43Z ERROR] FooDeadLetterQueue (consumer) (worker 1): Unsupported SASL mechanism
[2025-10-10T17:51:48Z ERROR] server error on API server (port 4000): connection closed
...
```

*"What WARN level logs do I have?"*

```
Showing 6 most recent log entries
Filters applied:
  - Level: WARN

[2025-10-10T16:45:04Z WARN] HTTP client not configured - missing API_KEY
[2025-10-10T16:50:05Z WARN] HTTP client not configured - missing API_KEY
...
```

**Tip**: Combine filters for better results. For example: "Show me ERROR logs with 'ClickHouse' in them" combines level filtering with search.

**Use cases:**
- Debugging application errors
- Monitoring infrastructure health
- Tracking data processing issues
- Finding specific events or patterns

---

### `get_infra_map` - **START HERE**

Get complete project topology showing all components with source file locations and data flow connections.

**Why use this first:**
- See all tables, topics, APIs, functions, workflows in one view
- Find where components are defined (`source_file` shows file paths)
- Understand data flow through connections
- Verify your code changes are reflected in infrastructure

**Optional search parameter:**
- Fuzzy, case-insensitive matching on component IDs and names
- Example: `search="user"` finds UserEvents, user_table, INGRESS_User
- Omit search to get the complete map

**Example prompts:**

*"Show me the infrastructure map"*

```toon
components[64]{id,type,name,source_file}:
  Bar,topic,Bar,app/ingest/models.ts
  local_Bar,table,Bar,app/ingest/models.ts
  INGRESS_Foo,api_endpoint,POST ingest/Foo,app/ingest/models.ts
  Foo__Bar,function,Foo__Bar,""
  BarAggregated_MV,sql_resource,BarAggregated_MV,""
  Bar_local_Bar,topic_table_sync,"Bar -> local_Bar",app/ingest/models.ts
  ...

connections[35]{from,to,type}:
  INGRESS_Foo,Foo,produces
  Foo,Foo__Bar,transforms
  Foo__Bar,Bar,produces
  Bar,Bar_local_Bar,ingests
  Bar_local_Bar,local_Bar,ingests
  ...

stats:
  total_components: 64
  by_type: {topic: 11, table: 28, api_endpoint: 11, ...}
```

*"Show me components related to Bar"*

```toon
components[8]{id,type,name,source_file}:
  Bar,topic,Bar,app/ingest/models.ts
  local_Bar,table,Bar,app/ingest/models.ts
  local_BarAggregated,table,BarAggregated,app/views/barAggregated.ts
  EGRESS_bar,api_endpoint,GET bar,app/apis/bar.ts
  Foo__Bar,function,Foo__Bar,""
  BarAggregated_MV,sql_resource,BarAggregated_MV,""
  Bar_local_Bar,topic_table_sync,"Bar -> local_Bar",app/ingest/models.ts
  ...

Search: 'Bar' | Matched: 8 component(s), 6 connection(s)
```

**Output format**: Compact TOON table format maximizes readability while minimizing token usage. Component IDs can be used to construct resource URIs: `moose://infra/{type}s/{id}`

**Use cases:**
- **First step when starting work** - understand project structure
- Find where components are defined (source_file paths)
- Trace data flow through connections
- Verify code changes are reflected

---

### `query_olap`

Execute read-only SQL queries against your local ClickHouse database.

**What you can ask for:**
- Query table data with filters, sorting, and aggregations
- Inspect table schemas and column information
- Count rows and calculate statistics
- List all tables in your database
- Results in table or JSON format

**Example prompts:**

*"What columns are in the UserEvents_1_0 table?"*

```
Query executed successfully. Rows returned: 4

| name      | type              | default_type | default_expression | comment | ...
|-----------|-------------------|--------------|-------------------|---------|
| userId    | String            |              |                   |         |
| eventType | String            |              |                   |         |
| timestamp | Float64           |              |                   |         |
| metadata  | Nullable(String)  |              |                   |         |
```

*"List all tables and their engines"*

```
Query executed successfully. Rows returned: 29

| name                        | engine                       |
|-----------------------------|------------------------------|
| Bar                         | MergeTree                    |
| BasicTypes                  | MergeTree                    |
| UserEvents_1_0              | MergeTree                    |
| UserEvents_2_0              | ReplacingMergeTree           |
| ReplicatedMergeTreeTest     | ReplicatedMergeTree          |
| BarAggregated_MV            | MaterializedView             |
...
```

*"Count the number of rows in Bar"*

```
Query executed successfully. Rows returned: 1

| total_rows |
|------------|
| 0          |
```

**Tip**: Ask the AI to discover table names first using "What tables exist in my project?" before querying them. Table names are case-sensitive in ClickHouse.

**Use cases:**
- Exploring data during development
- Validating data transformations
- Checking table schemas
- Debugging SQL queries
- Analyzing data patterns

**Safety:**
Only read-only operations are permitted (SELECT, SHOW, DESCRIBE, EXPLAIN). Write operations (INSERT, UPDATE, DELETE) and DDL statements (CREATE, ALTER, DROP) are blocked.

---

### `get_stream_sample`

Sample recent messages from Kafka/Redpanda streaming topics.

**What you can ask for:**
- View recent messages from any stream/topic
- Specify how many messages to sample
- Get results in JSON or pretty-printed format
- Inspect message structure and content

**Example prompts:**

*"Sample 5 messages from the Bar topic"*

```json
{
  "stream_name": "Bar",
  "message_count": 5,
  "partition_count": 1,
  "messages": [
    {
      "primaryKey": "e90c93be-d28b-47d6-b783-5725655c044f",
      "utcTimestamp": "+057480-11-24T20:39:59.000Z",
      "hasText": true,
      "textLength": 107
    },
    {
      "primaryKey": "b974f830-f28a-4a95-b61c-f65bfc607795",
      "utcTimestamp": "+057370-11-04T17:11:51.000Z",
      "hasText": true,
      "textLength": 166
    },
    ...
  ]
}
```

*"What data is flowing through the BasicTypes stream?"* (pretty format)

```markdown
# Stream Sample: BasicTypes

Retrieved 3 message(s) from 1 partition(s)

## Message 1
{
  "id": "bt-001",
  "timestamp": "2024-10-09T12:00:00Z",
  "stringField": "hello world",
  "numberField": 42,
  "booleanField": true
}

## Message 2
{
  "id": "bt-002",
  "timestamp": "2024-10-09T12:05:00Z",
  "stringField": "test",
  "numberField": 100,
  "booleanField": false
}
...
```

**Tip**: Use "List all streaming topics" first to discover available streams in your project.

**Use cases:**
- Debugging data flow issues
- Validating streaming transformations
- Inspecting message formats
- Troubleshooting pipeline failures

---

### `get_issues`

Proactively scan your Moose project for health issues and operational problems.

**What it checks:**
- Stuck mutations (long-running operations)
- Replication errors on replicated tables
- S3Queue ingestion failures
- Data parts and merge issues
- Background operation problems

**Example prompts:**

*"Check for any infrastructure issues"*

```toon
infrastructure_type: clickhouse
issues[2]{severity,component_type,component_name,issue_type,message}:
  error,table,UserEvents,stuck_mutation,"Mutation 0000000003 stuck for 2h 15m"
  warning,table,ReplicatedTable,replication_lag,"Replication lag: 15s behind leader"

summary:
  total_issues: 2
  by_severity: {error: 1, warning: 1}
```

*"Any problems with my tables?"*

```toon
infrastructure_type: clickhouse
issues[0]:
summary:
  total_issues: 0
  by_severity: {}
  by_component: {}
```

**Tip**: Run this when troubleshooting errors or performance issues. It automatically checks relevant diagnostics based on your infrastructure configuration.

**Use cases:**
- Troubleshooting unexplained errors
- Performance degradation investigation
- Proactive health monitoring
- Pre-deployment validation

---

## Example Workflows

### Understanding a New Project

```
You: "Can you explain this Moose project structure?"

AI: [Uses get_infra_map to see topology]

AI: This project has 11 topics, 28 tables, 11 API endpoints, and 3 functions.
Data flows like this:
- INGRESS APIs send data to topics (e.g., INGRESS_Foo → Foo topic)
- Functions transform between topics (Foo → Foo__Bar → Bar)
- Topics sync to tables (Bar_local_Bar sync → local_Bar table)
- SQL resources create views (BarAggregated_MV)

All components are defined in app/ingest/models.ts and app/functions/.
```

### Debugging a Data Pipeline

```
You: "My users table is empty, can you help me debug?"

AI: Let me check the infrastructure and data flow.
[Uses get_infra_map search="user" to see the pipeline]
[Uses get_issues to check for infrastructure problems]
[Uses get_logs level="ERROR" to check for errors]
[Uses query_olap to verify table is empty]
[Uses get_stream_sample to check if data is in the source stream]

AI: I found the issue - there are errors in the logs showing the streaming
function is failing. The stream has data, but it's not reaching the table.
```

### Validating Data Transformations

```
You: "Did my streaming function correctly transform the user data?"

AI: [Uses get_stream_sample on source stream]
[Uses query_olap on destination table]

AI: Yes, the transformation is working. I compared the source stream
messages with the destination table records, and the enrichment
fields are being added correctly.
```

## Advanced Configuration

### Custom Port

If you're running Moose on a non-default port, update the MCP configuration:

```bash
export MOOSE_HTTP_PORT=8080
moose dev
```

Then update your MCP client configuration to use port 8080 instead of 4000.

### Disabling the MCP Server

To run development mode without the MCP server:

```bash
moose dev --mcp=false
```

### Production Considerations

The MCP server is designed for local development only. It provides direct access to your infrastructure and should **never** be exposed in production environments.

The MCP server:
- Runs only in development mode (`moose dev`)
- Does not run in production mode (`moose prod`)
- Provides read-only access to sensitive infrastructure
- Should not be exposed over networks or proxied externally

## LLM-Optimized Documentation Feeds

Before handing control to an AI assistant, prime it with a compact doc bundle so it understands Moose primitives and terminology. We publish TypeScript and Python versions at `/llm-ts.txt` and `/llm-py.txt`, with optional `?path=` filters for specific sections.

See [LLM-optimized docs](/moose/llm-docs) for instructions on embedding these feeds into Claude, Cursor, Windsurf, or MCP clients alongside the live tools described above.

## Troubleshooting

### MCP Tools Not Appearing

1. Verify `moose dev` is running: `curl http://localhost:4000/mcp`
2. Check your AI client's MCP configuration is correct
3. Restart your AI client after updating configuration
4. Check the Moose logs for MCP-related errors: `moose logs --filter mcp`

### Connection Errors

If your AI client can't connect to the MCP server:

```bash
# Check if the dev server is running
curl http://localhost:4000/health

# Check MCP endpoint specifically
curl -X POST http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
```

### Empty Results

If tools return no data:
- Verify your dev server has been running long enough to generate data
- Check that infrastructure has been created: `moose ls`
- Try ingesting test data: `moose peek <table_name>`

## Related Documentation

- [Local Development](/moose/local-dev) - Development mode overview
- [Moose CLI Reference](/moose/moose-cli) - CLI commands and flags
- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification