MCP Server

Model Context Protocol server for AI agent integration — query data, manage configuration, and set up your provenance system using natural language.

The Provenance MCP server exposes your provenance data and configuration to AI agents via the Model Context Protocol. AI assistants can query interactions, search activity, view traces, monitor alerts, and create resource types, actions, and origins — all using natural language.

Setup

cd provenance-ai
pip install -r requirements.txt
python src/mcp/server.py

The MCP server connects to your Provenance API using the PROVENANCE_API_URL and PROVENANCE_API_KEY environment variables configured in .env.

Available tools

Configuration

Tool	Description
`get_resource_types`	List all resource types
`create_resource_type`	Create a new resource type
`update_resource_type`	Update a resource type
`get_actions`	List all actions
`create_action`	Create a new action
`update_action`	Update an action
`get_origins`	List all origins
`create_origin`	Create a new origin
`update_origin`	Update an origin

Interactions & Search

Tool	Description
`query_interactions`	Filter interactions by resource, action, origin, time
`create_interaction`	Record a new interaction
`search_activity`	Complex search with multiple filters
`get_trace`	Get interaction history for a UOW ID
`get_trace_summary`	Summary statistics for a trace

Notifications

Tool	Description
`get_subscribers`	List all notification subscribers
`create_subscriber`	Create a subscriber (webhook, adapter, etc.)
`update_subscriber`	Update a subscriber
`get_subscriptions`	List all subscriptions
`create_subscription`	Subscribe to a resource type + action
`update_subscription`	Update a subscription
`delete_subscription`	Delete a subscription
`pause_subscription`	Pause a subscription
`resume_subscription`	Resume a paused subscription
`get_adapters`	List available notification adapters
`get_queue_stats`	Queue statistics
`process_queue`	Process pending notifications

Alerts & Metrics

Tool	Description
`get_alerts`	List all alerts
`create_alert`	Create a threshold-based alert
`update_alert`	Update an alert
`delete_alert`	Delete an alert
`get_interaction_metrics`	List all interaction metrics
`create_interaction_metric`	Create a metric definition
`update_interaction_metric`	Update a metric
`delete_interaction_metric`	Delete a metric

Analytics & Dashboards

Tool	Description
`query_analytics`	Run analytics queries with metrics and dimensions
`get_dashboards`	List dashboards
`create_dashboard`	Create a new dashboard
`get_widgets`	Get widgets for a dashboard
`create_widget`	Create a new widget

Inbound Webhooks

Tool	Description
`get_inbound_sources`	List inbound webhook sources
`create_inbound_source`	Create a new inbound source
`get_inbound_mappings`	List inbound mappings
`create_inbound_mapping`	Create a payload-to-interaction mapping
`test_inbound_mapping`	Test a mapping against a sample payload

Secrets

Tool	Description
`get_secrets`	List all secret mappings
`create_secret`	Create a secret (encrypted in DB or external provider)
`test_secret`	Resolve a secret and return masked preview
`delete_secret`	Delete a secret mapping
`get_secret_providers`	List provider connections
`create_secret_provider`	Create a connection to an external secrets manager
`get_secret_provider_types`	List available provider types with config schemas

Setting up your system with AI

One of the most powerful uses of the MCP server is bootstrapping your provenance configuration. Instead of manually creating resource types, actions, and origins through the UI or API, you can describe your system to an AI agent and let it set everything up.

Describe your domain

Tell the agent what your system does. It will figure out the resource types, actions, and origins needed:

"I'm building an e-commerce platform. We have users, orders, products, and payments. Users can register, login, and update their profile. Orders can be placed, shipped, cancelled, and refunded. Payments are processed and can fail. The system has a web app, a mobile app, and a backend API."

The agent will create:

Resource types: USER, ORDER, PRODUCT, PAYMENT
Actions: REGISTER, LOGIN, UPDATE, PLACE, SHIP, CANCEL, REFUND, PROCESS, FAIL
Origins: WEBAPP, MOBILE_APP, BACKEND_API

Extend an existing setup

Ask the agent to check what's already configured and fill in the gaps:

"List my current resource types and actions. I'm adding a new inventory module — we need to track stock levels, warehouse transfers, and restock events."

The agent will call get_resource_types and get_actions first, then create only what's missing.

Map to auto-instrumentation

If you're using auto-instrumentation, the agent can help you align your configuration with your API routes:

"Here are my Express routes: POST /api/orders, POST /api/orders/:id/ship, POST /api/orders/:id/cancel, GET /api/users/:id, POST /api/payments/charge. Make sure I have the right resource types and actions for these."

The agent will check your existing config and create any missing resource types (ORDER, USER, PAYMENT) and actions (CREATE, SHIP, CANCEL, READ, CHARGE).

CI/CD bootstrap

Use the MCP in a CI/CD pipeline to ensure your provenance configuration matches your codebase. An AI agent can scan your route definitions and create missing resource types and actions before deployment.

Prompt ideas

Here are some prompts to get started:

Prompt	What the agent does
"Set up provenance tracking for a blog platform with posts, comments, and users"	Creates resource types, actions, and origins for a blog
"What resource types do I have? Add a NOTIFICATION type"	Lists existing types, creates the missing one
"I need actions for a document workflow: draft, review, approve, publish, archive"	Creates 5 domain-specific actions
"Add origins for GitHub Actions, Jenkins, and ArgoCD"	Creates 3 CI/CD origins
"Show me all interactions for order-456 and trace the full flow"	Queries interactions and gets the trace
"How many user registrations happened this week?"	Runs an analytics query
"Create a dashboard with a widget showing order volume by day"	Creates a dashboard and widget
"Are there any firing alerts?"	Checks alert status
"Set up a secret for my SendGrid API key"	Creates a provenance-stored secret
"Connect my AWS Secrets Manager in eu-west-1 and add a secret for the Stripe webhook signing key"	Creates provider connection + secret mapping

Notification pipeline

The agent can set up an entire notification pipeline in one conversation:

"I want to get a Slack notification whenever a new ORDER is created. Set up the subscriber, subscription, and any missing resource types or actions."

The agent will:

Check existing resource types and actions, create ORDER and CREATE if missing
List available adapters to find the Slack adapter
Create a subscriber pointing to your Slack webhook
Create a subscription linking ORDER + CREATE to the subscriber

Alert management

"Create an alert that fires when there are more than 100 failed payments in the last hour. Notify the ops-webhook subscriber."

The agent will list subscribers to find ops-webhook, then create the alert with the right condition and threshold.

"Show me all my alerts. Pause the one for failed logins — we're doing maintenance."

Metrics

"I want to track the average order value over the last 7 days. Create a metric for it."

The agent will list metric types, find the avg type, look up the ORDER resource type and relevant action, then create the metric definition.

"List my metrics. Disable the one tracking signup count — we don't need it anymore."

Querying data

Beyond configuration, the MCP server is useful for ad-hoc investigation:

"What happened to order-456?"

The agent calls query_interactions with resourceId: "order-456" and returns the full history.

"Show me all failed payments in the last 24 hours"

The agent calls search_activity with filters for resource type PAYMENT, action FAIL, and a 24-hour time range.

"How many deployments did we have this week, broken down by origin?"

The agent calls query_analytics with metrics: ["count"], dimensions: ["origin"], and a 7-day time range filtered to the DEPLOYMENT resource type.

AI service

The full Provenance AI service also includes REST endpoints for programmatic access:

POST /ai/query — Natural language to structured query
POST /ai/chat — Conversational interface
GET /ai/insights — AI-generated insights
POST /ai/suggest/dashboard — Dashboard recommendations
POST /ai/suggest/alert — Alert recommendations

On this page