misc/mcp-materialize-agents/README.md
The live data layer for apps and agents
Agents succeed when they can act in a loop with confidence. They perceive the world, think about what to do, act to change it, and then observe the results. The loop repeats until the goal is reached.
Large language models are improving quickly at the thinking step. The real challenge is perception. Agents need a live, trustworthy picture of the world to base their decisions on. That picture must always be correct and always reflect the current state.
The Materialize MCP Server provides that picture. It exposes your canonical business objects as live, database consistent data products.
Consider a customer support agent that needs to understand a customer's complete context:
With Materialize, this complex business logic is precomputed and instantly available. Agents can query with SQL, observe the current state, and see the effects of their actions reflected immediately. Every observation reflects the same point in time, so every action can be taken with confidence.
The Model Context Protocol (MCP) defines how agents connect to external tools and data. The Materialize MCP Server implements it for your operational data, giving agents:
The result is a shorter path from perception to confident action.
Vector stores and Materialize play different roles that complement each other.
Together, they give agents both the knowledge and the live context required to act intelligently.
Materialize incrementally maintains these views. Instead of recalculating them from scratch, it updates them as source data changes. Queries return in milliseconds even for complex joins, aggregations, and recursive logic.
Here's how you'd create a comprehensive customer view that combines data from multiple systems:
CREATE VIEW customer_360 AS
SELECT
c.customer_id,
c.email,
c.signup_date,
-- Subscription and revenue metrics
s.plan_tier,
s.monthly_revenue,
s.renewal_date,
CASE
WHEN s.renewal_date < NOW() + INTERVAL '30 days' THEN 'upcoming'
ELSE 'active'
END as renewal_status,
-- Support experience
COALESCE(sup.recent_tickets, 0) as recent_tickets_30d,
COALESCE(sup.avg_satisfaction, 0) as avg_satisfaction_score,
CASE
WHEN sup.recent_tickets > 5 THEN 'high'
WHEN sup.recent_tickets > 2 THEN 'medium'
ELSE 'low'
END as support_intensity,
-- Order activity
COALESCE(o.active_orders, 0) as active_orders,
COALESCE(o.lifetime_value, 0) as lifetime_value,
o.last_order_date,
-- Churn risk calculation
CASE
WHEN s.renewal_date < NOW() + INTERVAL '30 days'
AND sup.avg_satisfaction < 3 THEN 'high'
WHEN sup.recent_tickets > 5
AND sup.avg_satisfaction < 4 THEN 'medium'
WHEN o.last_order_date < NOW() - INTERVAL '90 days' THEN 'medium'
ELSE 'low'
END as churn_risk
FROM customers c
LEFT JOIN subscriptions s ON c.customer_id = s.customer_id
LEFT JOIN (
SELECT
customer_id,
COUNT(*) as recent_tickets,
AVG(satisfaction_score) as avg_satisfaction
FROM support_tickets
WHERE created_at > MZ_NOW() - INTERVAL '30 days'
GROUP BY customer_id
) sup ON c.customer_id = sup.customer_id
LEFT JOIN (
SELECT
customer_id,
COUNT(CASE WHEN status IN ('pending', 'processing') THEN 1 END) as active_orders,
SUM(total_amount) as lifetime_value,
MAX(order_date) as last_order_date
FROM orders
GROUP BY customer_id
) o ON c.customer_id = o.customer_id;
-- Index for instant lookups by customer
CREATE INDEX ON customer_360 (customer_id);
-- Documentation for agent discovery
COMMENT ON VIEW customer_360 IS 'Complete customer context including subscription, support, orders, and churn risk';
COMMENT ON COLUMN customer_360.churn_risk IS 'Risk level: high (immediate attention), medium (monitor), low (healthy)';
A customer retention agent monitors and acts on churn signals:
customer_360 to identify high-risk customers with upcoming renewalsEvery decision is based on live data that reflects the customer's current state across all systems—support, billing, orders—at the same moment in time.
pip install mcp-materialize-agents
Run with defaults:
mcp-materialize-agents
Or with uv:
uv run mcp-materialize-agents
| Argument | Env Var | Default | Description |
|---|---|---|---|
--mz-dsn | MZ_DSN | postgresql://materialize@localhost:6875/materialize | Materialize DSN |
--transport | MCP_TRANSPORT | stdio | Communication transport (stdio, sse) |
--host | MCP_HOST | 0.0.0.0 | Server host |
--port | MCP_PORT | 3001 | Server port |
--pool-min-size | MCP_POOL_MIN_SIZE | 1 | Minimum connection pool size |
--pool-max-size | MCP_POOL_MAX_SIZE | 10 | Maximum connection pool size |
--log-level | MCP_LOG_LEVEL | INFO | Logging level |
Once defined, agents can leverage this canonical business object:
-- Find customers needing immediate attention
SELECT customer_id, email, churn_risk, renewal_date
FROM customer_360
WHERE churn_risk = 'high'
AND renewal_date < NOW() + INTERVAL '7 days';
-- Understand a specific customer's complete context
SELECT * FROM customer_360 WHERE customer_id = 12345;
-- Monitor support experience trends
SELECT support_intensity, COUNT(*), AVG(lifetime_value)
FROM customer_360
GROUP BY support_intensity;
Queries return instantly, always reflect the current state, and maintain consistency across all the underlying data sources. Your agent never sees stale data or inconsistent states between systems.