MCP Server

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

Install the MCP server package:

pip install provenance-mcp

Or with uvx (no installation required):

uvx provenance-mcp

Configuration

Set your Provenance API credentials as environment variables:

export PROVENANCE_API_URL=https://your-provenance-api.example.com
export PROVENANCE_API_KEY=your-api-key

Then run the server:

provenance-mcp

IDE / Agent Configuration

For Cursor, Windsurf, Kiro, or other MCP-compatible editors, add to your MCP config:

{
  "mcpServers": {
    "provenance": {
      "command": "uvx",
      "args": ["provenance-mcp"],
      "env": {
        "PROVENANCE_API_URL": "https://your-provenance-api.example.com",
        "PROVENANCE_API_KEY": "your-api-key"
      }
    }
  }
}

The server connects to your Provenance API using the PROVENANCE_API_URL and PROVENANCE_API_KEY environment variables.

Available tools

Configuration

Interactions & Search

Notifications

Alerts & Metrics

Subscription tool parameters

The create_subscription and update_subscription tools accept these additional input parameters:

The get_subscriptions tool accepts:

Alert tool parameters

The create_alert and update_alert tools accept:

The get_alerts tool accepts:

Analytics & Dashboards

Inbound Webhooks

Secrets

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:

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:

1. Check existing resource types and actions, create ORDER and CREATE if missing
2. List available adapters to find the Slack adapter
3. Create a subscriber pointing to your Slack webhook
4. 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