A Developer's Guide to the Model Context Protocol in Spreedly

Every developer integrating a payments API has lived the same small misery: you're deep in your IDE with the mental model fully loaded, you need to know the exact request schema for a purchase call, and you're about to blow the whole thing up by opening a browser tab. If you’d like a fix for that (sure you would, why wouldn’t you?), then you’re in luck. 

This article explains what the Model Context Protocol is, why payments developers should care, and how to connect your AI coding tools to Spreedly's full documentation and live API environment in under five minutes. You’ll also get 25 queries that you can use to get real work done once you’re ready to go! 

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard that connects AI assistants to external data sources and tools through a single, structured interface, replacing the custom integration every new connection used to require.

Before MCP, connecting an AI tool to any external system meant building a new integration for every new combination. Anthropic, who launched MCP in November 2024, described it as an "N×M" problem: every AI client needing its own connector to every data source. MCP collapses that into a single protocol. The analogy that's stuck, and stuck for good reason, is that MCP is the USB-C for AI: one standard that works with any compatible device.

MCP server downloads went from somewhere 100,000 in November 2024 to over 8 million by April 2025. You don’t have to be a mathlete to see that this is a not-insignificant difference in values for those two numbers. 

OpenAI went ahead and adopted the standard across its Agents SDK and ChatGPT desktop in March 2025, and then Google DeepMind followed in short order. 

In December 2025, Anthropic donated MCP governance to the Agentic AI Foundation under the Linux Foundation, which turned it into a vendor-neutral open standard that no single company owns or controls. Every major AI platform now ships with MCP support, so the developer toolchain has the connective tissue needed to really start to thrive.

Why payments developers specifically should care

You already know the pain points of payments API integration, so let's get straight to the cost.

You're in Cursor or VS Code or Claude Code. You need the exact field names for a tokenization request. You alt-tab to a browser, open the Spreedly docs, scan through the correct page, copy what you need, and come back. 

Well that’s good, but here’s the thing: Research from UC Irvine's Gloria Mark finds that each context switch costs 23 minutes of recovery time, meaning 23 minutes to get your brain back to where it was before you went looking. A survey of 3,500 engineers by Atlassian found that context switching between tools ranks third among the biggest productivity killers for developers in the industry today.

Payments API integration has more surface area for that kind of friction than most technical domains. Authentication, tokenization, gateway routing, transaction schemas, error codes, PCI scope, receiver configuration: the documentation is thorough, and rightfully so. But when it lives in a separate application, every lookup becomes a productivity tax.

Teams that have moved to context-aware AI tooling consistently report saving 40 to 60 minutes per developer per day. More precisely, the median time to integrate an API drops from 18 hours to approximately 4.2 hours when MCP is in the workflow, a 4x compression on the slowest and most error-prone stage of building.

For a developer working against an integration deadline, that's the difference between shipping this sprint and explaining to a product manager why you didn't and making them have to figure out how to plan the next sprint based on your inability to deliver. You probably won’t go to the penalty box, as explained in Slap Shot, but you may feel shame.

Spreedly's two MCP servers, and which one you need

Know which server you need before you start configuring, or you'll end up reaching for a sledgehammer when the job calls for a scalpel. One hopes no further explanation is required for that analogy. 

The docs MCP server lives at https://developer.spreedly.com/mcp and takes about one line of JSON to set up. Paste the URL, save the config, and you're done. Your AI tools get access to Spreedly's full documentation and API specification, including schemas, endpoint details, code snippets, and request bodies, through nine built-in tools you can call with plain language. It's the right starting point whether you're evaluating Spreedly or actively building against it.

The self-hosted MCP server is a different animal. It lives on GitHub, needs your Spreedly Environment Key and Access Secret, and connects your AI tools to a live Spreedly environment. When you've got it configured, you can tokenize payment methods, authorize and capture transactions, manage gateways, and more, all from natural language prompts inside your IDE. Every capability beyond read-only is gated behind environment variable flags that default to false, so you opt into what you actually need and nothing runs by surprise.

Think of the docs server as your always-on reference assistant and the self-hosted server as a live connection to the API. Most developers will set up the docs server first and come back to the self-hosted version when they're ready to run real workflows.

Set up the docs MCP server in five minutes

This is the shortest section in the post because the setup genuinely takes five minutes, and the only way to make it take longer is to overthink it.

For Cursor, add the following to .cursor/mcp.json in your project root:

For VS Code (Windsurf), the same config goes into your MCP client settings. Same URL, different file location per your editor's documentation.

For Claude Desktop, add it to ~/.claude/mcp.json with the same structure. Full path guidance is in the Spreedly MCP docs.

Once the config is saved, open a new chat in your AI assistant and ask: "What endpoints does Spreedly have for managing gateways?" A structured response drawn from Spreedly's API specification means you're in business.

Set up the self-hosted MCP server

The self-hosted server takes a few more steps. Still under ten minutes, but you'll need your credentials handy.

Add the following to your MCP client configuration:

To grab your credentials, log into app.spreedly.com and copy your environment key from the settings page. Generate or retrieve your Access Secret from the same spot.

Three environment variable flags control what the server can actually do: PAYMENT_METHOD_TOKENIZATION_ENABLED, TRANSACTION_INITIATION_ENABLED, and ADMINISTRATIVE_ENABLED. All three start at false. A good habit is to enable only what your current use case requires and expand from there. The GitHub repo has recommended configuration profiles worth reading before you start toggling.

The defaults are deliberate. The architecture rewards doing the minimum required for what you're actually building.

25 queries to get real work done

The first 20 work with the docs server, so nothing beyond the config you already set up is required. The last five need the self-hosted server with the relevant flags on. Type them into your AI assistant's chat the way you'd ask a colleague who happened to have the entire Spreedly API spec committed to memory.

API discovery and documentation

1. "What endpoints does Spreedly have for managing gateways?"
2. "Show me all available payment method endpoints and what each one does."
3. "What authentication methods does Spreedly support?"
4. "What's the complete request schema for creating a purchase transaction?"
5. "What response fields does Spreedly return when a transaction is declined?"
6. "Find all documentation related to PCI compliance and tokenization."
7. "What are the differences between a purchase and an authorize call in Spreedly?"

Code generation and integration help

8. "Generate a Node.js code snippet for tokenizing a credit card with Spreedly."
9. "Write a Python function that creates a gateway and handles the response."
10. "Give me a Ruby example for running a purchase against a specific gateway token."
11. "What's the curl command to retrieve a transaction by its token?"
12. "Show me how to implement a two-step authorize-then-capture flow in TypeScript."
13. "Write error handling logic for Spreedly's most common decline codes."
14. "How do I structure a request to use a stored payment method for a recurring charge?"

Schema and parameter detail

15. "What parameters are required versus optional when creating a receiver?"
16. "What specific fields come back in a gateway's response object?"
17. "Show me the full request body schema for authorizing a payment."
18. "What optional parameters can I pass when updating a payment method?"
19. "What does error code 422 mean in Spreedly and what should I check first?"
20. "List all the fields in the transaction response schema and what each one represents."

Live environment and transaction workflows (self-hosted server)

21. "List all gateways currently configured in my Spreedly environment."
22. "Show me the last 10 transactions and their authorization status."
23. "Tokenize this test card number and return the payment method token."
24. "Run an authorize call against my Stripe gateway using payment method token [X] for $10.00."
25. "Find transaction [token] and show me the full response including any gateway message."

What the Spreedly MCP server doesn't do

We should be very clear about scope before you get started.

The MCP server handles documentation access and direct API calls. It doesn't make architectural decisions. Multi-gateway routing strategy, PCI scope management, integration design: those conversations stay with your team. 

The server surfaces the schemas and documentation your engineers need; your engineers do the thinking. The self-hosted server also works within your existing Spreedly environment permissions, so the security posture matches whatever access you've already set up.

Think of it like a very well-read intern who can pull any page of any manual, write solid first-draft code from memory, and execute API calls when you hand them the keys. The judgment calls still sit with the senior engineer.

Your AI tools are only as useful as the context they carry

Most of the friction in a payments integration is informational rather than technical, and the hold-up is usually the constant tab-switching to find a schema, chase down a parameter, or remember how a particular error should be handled, all while the mental model you spent 20 minutes loading slowly leaks out of your head.

The Spreedly MCP server keeps that context where the work is.The Spreedly MCP server keeps that context where the work is. A developer who used to burn 20 minutes hunting down the right endpoint and stitching together a working snippet can now do it inside the same conversation where they're writing the implementation, which is a pretty good return on a five-minute config change.

78% of enterprise teams now report at least one MCP-backed agent in production, so the AI coding tools are already in your workflow whether you've thought about it or not. The Spreedly MCP server gives them the payments context they need to get things done quickly. 

The setup documentation is at developer.spreedly.com/docs/mcp and the self-hosted server is at github.com/spreedly/spreedly-mcp.

Every time an engineer breaks focus to go hunting for a schema or an endpoint, you're paying 23 minutes to get them back. Set up the MCP server and stop paying that line item on the engineering time tax.