The MCP Integration Playbook: How to Wire Your AI Agent to Supabase, Stripe, and Any API Using Model Context Protocol

Q: Can I use MCP to integrate Stripe payments into my AI agent?

Yes. Stripe publishes an official MCP server at @stripe/mcp. Configure it with your STRIPE_SECRET_KEY (use a restricted key scoped to only the resources you need) and your agent gains access to tools like create_customer, create_payment_link, list_subscriptions, and create_refund. The server supports both stdio and HTTP transport modes.

Q: How do I ship MCP configurations inside a workspace template?

Include your MCP server definitions in the workspace's .openclaw/mcp.json file. Use environment variable placeholders (like SUPABASE_URL) instead of hardcoded credentials so that users supply their own keys at instantiation time. When someone downloads and instantiates the template, they fill in their credentials and the agent connects to their own service accounts automatically.

Model Context Protocol has crossed a threshold. With 97 million monthly SDK downloads and over 1,000 community-built servers, MCP is no longer an experiment — it is the standard interface between AI agents and the outside world. Yet most coverage stops at "what MCP is" without showing you how to actually wire it to the services your agent needs.

This guide is different. We will walk through MCP architecture just enough to understand the moving parts, then build two real integrations: Supabase for database access and Stripe for payment operations. By the end, you will have a reusable pattern for connecting your agent to any API that has (or can have) an MCP server — and you will know how to package those configurations into shareable workspace templates.

MCP Architecture in Five Minutes

Before we touch configuration files, you need a mental model of how MCP works. The architecture has three layers:

┌─────────────────────────────────────────────────────┐
│                    YOUR AI AGENT                     │
│              (Claude, OpenClaw, etc.)                │
│                                                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │ MCP Client  │  │ MCP Client  │  │ MCP Client  │ │
│  │ (Supabase)  │  │  (Stripe)   │  │  (GitHub)   │ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘ │
└─────────┼────────────────┼────────────────┼─────────┘
          │ stdio/HTTP     │ stdio/HTTP     │ stdio/HTTP
          ▼                ▼                ▼
   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
   │  MCP Server  │ │  MCP Server  │ │  MCP Server  │
   │  (Supabase)  │ │   (Stripe)   │ │   (GitHub)   │
   └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
          │ HTTPS          │ HTTPS          │ HTTPS
          ▼                ▼                ▼
   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
   │  Supabase    │ │  Stripe      │ │  GitHub      │
   │  REST API    │ │  REST API    │ │  REST API    │
   └──────────────┘ └──────────────┘ └──────────────┘

Host — the application that runs your agent (Claude Desktop, an OpenClaw runtime, VS Code with Copilot, etc.). The host manages MCP client lifecycle.

MCP Client — one client per server connection. The client maintains a 1:1 session with a single MCP server, handling capability negotiation and message routing.

MCP Server — a lightweight process that exposes three primitives:

Tools — functions the agent can call (e.g., execute_sql, create_customer)
Resources — read-only data the agent can access (e.g., database schemas, file contents)
Prompts — reusable prompt templates the server can offer

The protocol itself is JSON-RPC 2.0 over one of two transports:

stdio — the server runs as a child process; communication happens over stdin/stdout. Simple, local, zero network config.
Streamable HTTP — the server runs as a network service. Better for remote deployments, shared infrastructure, and production use.

Most community servers use stdio. You configure them once, and your agent spawns them on demand.

The Configuration File

Every MCP-capable agent reads server definitions from a configuration file. The exact location varies by host, but the structure is universal:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@namespace/mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

For Claude Desktop, this lives at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). For OpenClaw workspaces, it goes in .openclaw/mcp.json. For VS Code with GitHub Copilot, it is .vscode/mcp.json in your project root.

The key insight: MCP configuration is declarative and portable. A JSON block that works in Claude Desktop works in any MCP-capable host with zero changes. This portability is what makes MCP configurations ideal for shipping inside workspace templates.

Integration 1: Supabase — Give Your Agent a Database

Supabase is a popular open-source Firebase alternative built on PostgreSQL. The official Supabase MCP server lets your agent query tables, inspect schemas, manage migrations, and even access edge functions — all through natural language.

Step 1: Get Your Supabase Credentials

You need two values from your Supabase project dashboard:

Project URL — found in Settings > API. Looks like https://abcdefghijkl.supabase.co
Service Role Key — found in Settings > API > Project API keys. This is the service_role key (not anon).

The service role key bypasses Row Level Security. For production agents, consider using the anon key with proper RLS policies instead. We will address security in detail later.

Step 2: Configure the MCP Server

Add this block to your agent's MCP configuration:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server", "--read-only"],
      "env": {
        "SUPABASE_URL": "https://abcdefghijkl.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }
}

The --read-only flag is critical for initial setup. It restricts the server to SELECT queries only, preventing your agent from accidentally dropping tables while you are still learning the integration.

Step 3: Verify the Connection

Restart your agent (or reload the MCP configuration). Then ask:

"List all tables in my Supabase database and describe their schemas."

Your agent should call the list_tables tool and return a structured overview of your database. If you see an error, check that your service role key is correct and that the project URL includes the https:// prefix.

Available Tools

The Supabase MCP server exposes a rich set of tools:

Tool	Description
`list_tables`	List all tables with their schemas and row counts
`execute_sql`	Run arbitrary SQL (respects --read-only flag)
`list_extensions`	Show installed PostgreSQL extensions
`list_migrations`	List applied database migrations
`apply_migration`	Apply a new SQL migration (requires write access)
`create_branch`	Create a Supabase database branch for testing
`get_logs`	Fetch API gateway, Postgres, and auth logs
`get_project_url`	Return the project URL for reference
`get_anon_key`	Return the anon API key

Practical Example: Building a User Analytics Agent

With Supabase connected, you can build agents that answer business questions in real time. Consider this conversation:

You: "How many users signed up in the last 7 days, broken down by country?"

Agent: I'll query the users table for recent signups.

[Calls execute_sql with:
  SELECT country, COUNT(*) as signups
  FROM auth.users
  WHERE created_at > now() - interval '7 days'
  GROUP BY country
  ORDER BY signups DESC
]

Agent: Here's the signup breakdown for the past week:
  - United States: 1,247
  - Germany: 389
  - Japan: 312
  - Brazil: 298
  - United Kingdom: 276
  ...

No dashboard needed. No SQL client. The agent queries your production database directly and presents the results in natural language. This is the power of MCP — your agent gains the ability to work with real data, not just generated text.

Enabling Write Access

Once you are comfortable with read-only mode, remove the --read-only flag to unlock write operations:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"],
      "env": {
        "SUPABASE_URL": "https://abcdefghijkl.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }
}

With write access, your agent can apply migrations, seed data, and modify records. This is powerful for development workflows — you can tell your agent "add a last_login column to the users table and backfill it from the auth logs" and it will generate and apply the migration.

A word of caution: always test write operations on a Supabase branch (the create_branch tool exists for exactly this purpose) before applying them to production.

Integration 2: Stripe — Give Your Agent Payment Powers

Stripe is the most widely used payment infrastructure for SaaS products. Connecting it to your agent via MCP means your agent can check subscription statuses, generate payment links, issue refunds, and pull financial reports — all through conversation.

Step 1: Create a Restricted API Key

Never use your Stripe secret key directly. Instead, create a restricted key:

Go to the Stripe Dashboard > Developers > API keys
Click "Create restricted key"
Name it something like "MCP Agent - Read/Write"
Grant only the permissions your agent needs:
- Customers: Read/Write
- Payment Links: Write
- Subscriptions: Read
- Invoices: Read
- Refunds: Write (if needed)
Save and copy the key (starts with rk_live_ or rk_test_)

Using a restricted key limits the blast radius if the key is ever exposed. Your agent can only access what you explicitly permit.

Step 2: Configure the MCP Server

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp", "--tools=all"],
      "env": {
        "STRIPE_SECRET_KEY": "rk_test_51..."
      }
    }
  }
}

The --tools=all flag enables all available tools. You can also pass --tools=customers.create,payment_links.create to enable only specific tools for tighter control.

Step 3: Test With a Query

After restarting your agent:

"Show me all active subscriptions with their monthly revenue."

Your agent calls list_subscriptions with status: "active" and aggregates the results. If you are using a test mode key (rk_test_), you will see test data — which is exactly what you want for initial setup.

Available Tools

The Stripe MCP server provides tools that map closely to the Stripe API:

Tool	Description
`create_customer`	Create a new Stripe customer
`list_customers`	List customers with optional filters
`create_product`	Create a product definition
`create_price`	Attach a price to a product
`create_payment_link`	Generate a shareable payment link
`list_subscriptions`	List subscriptions with status filters
`create_invoice`	Create a draft invoice
`create_refund`	Issue a refund on a charge or payment intent
`get_balance`	Retrieve current account balance
`list_payment_intents`	List recent payment intents

Practical Example: Automated Billing Ops

Here is where it gets interesting. With Stripe connected, your agent becomes a billing operations assistant:

You: "A customer emailed asking for a refund on invoice INV-0042. Process it
     if the invoice is less than 30 days old."

Agent: Let me look up that invoice.

[Calls list_invoices with search for INV-0042]

Agent: Found it. Invoice INV-0042 for $199.00 was paid on March 1, 2026 —
       22 days ago. This is within the 30-day window.

[Calls create_refund with the payment intent ID]

Agent: Refund processed. $199.00 will be returned to the customer's card
       within 5-10 business days. Should I draft a confirmation email to
       the customer?

This workflow would normally require a support agent to log into Stripe, find the invoice, verify the date, process the refund, and then respond to the customer. With MCP, the AI agent handles the entire sequence in seconds.

Combining Multiple MCP Servers

The real power of MCP shows up when you combine servers. An agent with both Supabase and Stripe can answer questions that span data sources:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server", "--read-only"],
      "env": {
        "SUPABASE_URL": "https://abcdefghijkl.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "eyJhbGciOiJIUzI1NiIs..."
      }
    },
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp", "--tools=all"],
      "env": {
        "STRIPE_SECRET_KEY": "rk_test_51..."
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Now your agent can correlate application data (Supabase) with payment data (Stripe) and code changes (GitHub). Ask "which customers on the Pro plan have filed the most support tickets this month?" and the agent will join across both data sources to give you an answer.

This multi-server composition is the architectural pattern that makes MCP-powered agents genuinely useful for business operations — not just single-tool wrappers.

Shipping MCP Configs Inside Workspace Templates

Here is where everything connects to the broader agent ecosystem. When you build an agent workspace that relies on specific MCP servers, those server configurations are part of the workspace's identity. Without them, the workspace is incomplete — like shipping a web app without its docker-compose.yml.

The Template Configuration Pattern

In an OpenClaw workspace template, MCP configurations live in .openclaw/mcp.json:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server", "--read-only"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_SERVICE_ROLE_KEY": "${SUPABASE_SERVICE_ROLE_KEY}"
      }
    },
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp", "--tools=all"],
      "env": {
        "STRIPE_SECRET_KEY": "${STRIPE_SECRET_KEY}"
      }
    }
  }
}

Notice the ${VARIABLE} placeholders. These are not hardcoded secrets — they reference environment variables that the user provides when they instantiate the template. The template defines which servers to connect and how to configure them. The user supplies their own credentials.

This pattern means a workspace template author can build a complete "SaaS Billing Operations Agent" — with Supabase for user data, Stripe for payments, and a carefully crafted system prompt — and share it as a ready-to-use package. The person who downloads it just needs to plug in their own Supabase project URL and Stripe key.

Community-driven template platforms like ClawAgora make this distribution seamless. A contributor uploads their template with the MCP configuration included, and anyone can browse, download, and instantiate it with their own credentials. The MCP configs ship as part of the template, so users do not have to figure out which servers to install or how to configure them.

Security Best Practices for Template MCP Configs

When shipping MCP configurations in templates, follow these rules:

Never hardcode credentials. Always use environment variable placeholders.
Default to read-only. Include --read-only flags where available and document when and why to remove them.
Use restricted API keys. Document the minimum permissions required for each server.
Include a security note. Add a SECURITY.md or a section in your README explaining what each MCP server accesses and why.
Pin server versions. Instead of @supabase/mcp-server (latest), use @supabase/mcp-server@1.2.3 to prevent supply chain surprises.

Building Your Own MCP Server

What if the service you need does not have an MCP server yet? Building one is straightforward with the official TypeScript SDK:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-api-server",
  version: "1.0.0",
});

// Define a tool
server.tool(
  "get_weather",
  "Get current weather for a city",
  {
    city: z.string().describe("City name"),
    units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
  },
  async ({ city, units }) => {
    const response = await fetch(
      `https://api.weatherapi.com/v1/current.json?key=${process.env.WEATHER_API_KEY}&q=${city}`
    );
    const data = await response.json();
    const temp = units === "celsius" ? data.current.temp_c : data.current.temp_f;

    return {
      content: [
        {
          type: "text",
          text: `Current weather in ${city}: ${temp}°${units === "celsius" ? "C" : "F"}, ${data.current.condition.text}`,
        },
      ],
    };
  }
);

// Connect via stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);

Publish this as an npm package, and anyone can add it to their MCP configuration:

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "my-weather-mcp-server"],
      "env": {
        "WEATHER_API_KEY": "your-key"
      }
    }
  }
}

The MCP TypeScript SDK handles all the protocol negotiation, message framing, and error handling. You focus on the business logic — fetch data from the API and return it in a structured format. SDKs are also available for Python, Java, Kotlin, C#, Swift, and Go, so you can build servers in whatever language your team prefers.

The MCP Integration Pattern: A Checklist

Whether you are connecting to Supabase, Stripe, or any other service, the integration pattern is the same:

Find or build the MCP server. Check the MCP server registry and community directories for existing servers. Over 1,000 servers exist as of March 2026.
Get credentials. Create service-specific API keys with minimum required permissions. Prefer restricted or read-only keys.
Add the configuration. Drop the server definition into your agent's MCP config file. Use environment variables for secrets.
Test in read-only mode. Verify the connection and tool discovery before enabling write operations.
Iterate on permissions. Expand access only as your use case requires. Start narrow, widen gradually.
Package for sharing. If you are building a reusable workspace, include the MCP config with ${VARIABLE} placeholders and document the required credentials.

This six-step pattern works for any service. The MCP ecosystem is growing fast enough that most major SaaS tools either have an official server or a well-maintained community server. For everything else, building your own takes an afternoon with the SDK.

What's Next for MCP

The protocol is evolving rapidly. A few developments worth watching:

Streamable HTTP transport is replacing the older SSE-based remote transport, enabling better support for stateless and resumable connections.
OAuth 2.1 integration for MCP server authentication is in active development, which will simplify credential management for remote servers.
Elicitation — a proposed feature that lets MCP servers ask the user for additional information mid-operation — is being discussed for future spec versions.
Agent-to-agent communication via MCP is emerging as a pattern, where one agent's MCP server exposes capabilities that other agents can consume.

The trajectory is clear: MCP is becoming the universal adapter layer between AI agents and the digital world. Learning to configure and build MCP servers today puts you ahead of the curve for whatever comes next.

Frequently Asked Questions

What is the Model Context Protocol (MCP) and why does it matter for AI agents?

MCP is an open standard created by Anthropic that defines how AI agents discover and call external tools. Instead of hard-coding API calls into prompts, MCP provides a structured JSON-RPC 2.0 interface where servers advertise capabilities (tools, resources, prompts) and clients (your agent) invoke them. With 97 million+ monthly SDK downloads and over 1,000 community servers, MCP has become the de facto standard for agent-to-service communication. It matters because it decouples the agent from specific APIs — your agent learns MCP once and can talk to any MCP-compliant server.

How do I connect my AI agent to Supabase using MCP?

Install the official Supabase MCP server by adding it to your agent's MCP configuration file. Set the command to npx with args -y @supabase/mcp-server --read-only and provide your SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY as environment variables. The server exposes tools like list_tables, execute_sql, and get_logs that your agent can call directly. Start with --read-only mode for safety and remove the flag only when you specifically need write operations like applying migrations.

Can I use MCP to integrate Stripe payments into my AI agent?

Yes. Stripe publishes an official MCP server at @stripe/mcp. Configure it in your MCP config with your STRIPE_SECRET_KEY — ideally a restricted key scoped to only the resources your agent needs — and your agent gains access to tools like create_customer, create_payment_link, list_subscriptions, and create_refund. Use test mode keys (rk_test_) during development and switch to live keys for production. The --tools flag lets you restrict which Stripe tools are available to the agent.

How do I ship MCP configurations inside a workspace template?

Include your MCP server definitions in the workspace's .openclaw/mcp.json file. Use environment variable placeholders (like ${SUPABASE_URL}) instead of hardcoded credentials so that users supply their own keys at instantiation time. When someone downloads and instantiates the template, they fill in their credentials and the agent connects to their own service accounts automatically. Always default to read-only modes, document required permissions, and pin server package versions for security.

What is the difference between MCP stdio and HTTP transport?

Stdio transport launches the MCP server as a local child process and communicates over standard input/output. It is simpler to set up and ideal for local development — most community servers use this mode. HTTP transport (specifically Streamable HTTP, which is replacing the older SSE-based approach) runs the MCP server as a standalone network service. HTTP is better for remote deployments, shared infrastructure, and production environments where you need the server accessible from multiple clients or behind a load balancer. Choose stdio for personal agent setups, HTTP for team or production deployments.