MCP for AI Agents

VSCode

Connect AI assistants to your Malloy semantic models using the Model Context Protocol (MCP). Publisher includes a built-in MCP server that exposes your models to AI agents.

Quick Start

This works for MCP clients that support HTTP endpoints directly.

1. Start Publisher

npx @malloy-publisher/server --server_root /path/to/your/packages

The AI sees all packages under your server_root directory. The MCP server starts automatically at http://localhost:4040/mcp.

For other deployment options (Docker, git clone), see Publish Your Models.

2. Configure Your MCP Client

{
  "mcpServers": {
    "malloy-publisher": {
      "url": "http://localhost:4040/mcp"
    }
  }
}

3. Start Asking Questions

Once connected, try prompts like:

• "What Malloy packages are available?"

• "Show me the measures in the orders model"

• "Query total revenue by month"

Stdio Bridge (VS Code, Claude Desktop, etc.)

Some MCP clients (VS Code, Claude Desktop) require stdio-based commands instead of HTTP. Use the bridge script to translate between protocols.

Prerequisites

• Python 3.x installed

• Malloy Publisher MCP Server running on localhost:4040/mcp

1. Download the Bridge

Download malloy_bridge.py

Save it somewhere accessible, for example: ~/malloy_bridge.py

2. Configure Your MCP Client

Example configuration for VS Code (settings.json or .vscode/mcp.json):

{
  "mcp": {
    "servers": {
      "malloy": {
        "command": "python3",
        "args": ["/full/path/to/malloy_bridge.py"]
      }
    }
  }
}

Replace /full/path/to/malloy_bridge.py with the actual path where you saved the bridge script.

Testing the Bridge

Test the bridge script:

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python3 /path/to/malloy_bridge.py

Check /tmp/malloy_bridge.log for debugging information.

MCP Tools

Publisher exposes these tools to AI agents:

Discovery

Query Execution

Agent Retrieval Tools and Skills

Alongside the core MCP server on :4040, Publisher runs a second MCP server for agents on :4041 (set by AGENT_MCP_PORT). It serves two read-only retrieval tools plus the bundled agent skills, configured the same way as the core server but on the agent endpoint:

{
  "mcpServers": {
    "malloy-publisher-agent": {
      "url": "http://localhost:4041/mcp"
    }
  }
}

Retrieval tools

Use malloy_getContext in two phases: call it once with just a query to discover the most relevant sources and views, then optionally call it again with sourceName set to focus on the fields within one source. The environmentName, packageName, and modelPath it returns map directly onto malloy_executeQuery, so an agent can go from a question to a grounded query without guessing field names.

Skills as MCP prompts

Publisher also ships a set of agent skills: short guides that teach an agent how to write Malloy, choose charts, and verify results. Skill-aware hosts (such as Claude Code and Claude Desktop) load the skill files directly. For hosts that only ingest MCP, the agent server also exposes each skill as an MCP prompt, so the same guidance is available either way: list them with prompts/list on the agent endpoint and fetch one with prompts/get.

Example Prompts

Once connected, try these prompts:

Exploration:

• "Use Malloy to run an exploratory analysis on the FAA dataset"

• "Help me understand the ecommerce data and create charts"

Specific queries:

• "How many flights were there by carrier last year?"

• "What's the average order value by region?"

Analysis:

• "Why did revenue drop in March? Investigate by region and product."

Best Practices for AI-Friendly Models

Use Descriptive Names

// Good - AI understands intent
measure: customer_lifetime_value is ...
measure: monthly_recurring_revenue is ...

// Bad - cryptic abbreviations
measure: clv is ...
measure: mrr is ...

Add Annotations

Use tags to add metadata that AI agents can read:

source: orders is duckdb.table('orders.parquet') extend {
  # "Revenue after discounts and returns"
  measure: net_revenue is sum(amount - discount - returns)
}

Define Common Views

Pre-built views guide AI toward valid queries:

view: executive_summary is {
  aggregate: total_revenue, order_count, customer_count
}

view: regional_breakdown is {
  group_by: region
  aggregate: total_revenue, order_count
}

Resources

• MCP Demo Video

• Model Context Protocol Spec

• Publisher GitHub