Key Concepts

This page covers the foundational concepts behind PayMongo's MCP server — what the protocol is, how it maps to PayMongo's API, and the terms you'll encounter when setting up and using it. If you're new to MCP, start here before moving to setup.

What is MCP

Model Context Protocol (MCP) is an open standard that defines how AI assistants connect to external data sources and tools. It gives AI models a structured, secure way to call external services — so instead of an AI assistant being limited to what it already knows, it can fetch live data and trigger real actions on your behalf.

MCP separates the AI model from the systems it works with. The model doesn't connect to PayMongo directly — it connects to an MCP server, which handles authentication, translates requests into API calls, and returns structured results the model can reason over. This separation keeps credentials out of the model layer and gives you a clear boundary to audit and control.

PayMongo's MCP server implements this standard on top of the PayMongo API. It is not a separate system — it is a structured interface that exposes existing API capabilities to MCP-compatible AI environments.

Core concepts

MCP host

The AI environment where you interact with PayMongo through natural language. This is typically an AI assistant or IDE plugin that supports MCP — such as Claude. The host is responsible for managing the connection to the MCP server and presenting results back to you.

MCP server

PayMongo's MCP server is the intermediary between your AI host and the PayMongo API. It receives tool calls from the host, authenticates them using your API credentials, executes the corresponding API request, and returns a structured response.

The MCP server runs on PayMongo's infrastructure. You don't host or manage it — you connect to it.

Tools

Tools are the discrete actions the MCP server exposes to the AI host. Each tool maps to one or more PayMongo API operations. When you ask your AI assistant to look up a payment or issue a refund, the host selects the appropriate tool, the MCP server executes it, and the result is returned to the host.

Tools fall into two categories:

Category	What it does	Examples
Read	Retrieves data from your PayMongo account	Get payment, list payouts, retrieve dispute
Write	Triggers an action that modifies data	Issue refund, enable webhook, update endpoint

Write tools require explicit confirmation in your AI environment before execution. Read tools execute immediately.

Tool call

A tool call is a single invocation of a tool by the AI host. When you ask a question or request an action, the host may make one or more tool calls to the MCP server to assemble a complete response. Tool calls are logged and visible in your AI environment's activity history.

Context

Context is the information your AI host passes to the MCP server alongside a tool call — typically the parameters needed to execute the right API request. For example, when you ask about a specific payment, the host extracts the payment ID from your message and includes it as context in the tool call.

The quality of the context your host passes directly affects the accuracy of the result. If a request is ambiguous — for example, asking for "recent failed payments" without a time range — the host may ask a clarifying question before making the tool call.

Session

A session is an active connection between your AI host and the MCP server. Sessions are authenticated using your PayMongo API key and inherit the permissions and environment of that key — a test key session can only access test data, a live key session can only access live data.

Sessions do not persist state between conversations. Each new conversation in your AI host starts a fresh session.

Supported tools and actions

The following tools are available through PayMongo's MCP server, organized by product area.

Payment Acceptance

Tool	Category	Description
`get_payment`	Read	Retrieve a payment by ID.
`list_payments`	Read	List payments with optional filters for status, date range, and amount.
`get_payment_intent`	Read	Retrieve a payment intent by ID.
`list_payment_intents`	Read	List payment intents with optional filters.
`get_refund`	Read	Retrieve a refund by ID.
`create_refund`	Write	Issue a refund against a paid payment.
`get_dispute`	Read	Retrieve a dispute by ID.
`list_dispute`	Read	List disputes with optional filters for status and date range.

Payouts

Tool	Category	Description
`get_payout`	Read	Retrieve a payout by ID.
`list_payouts`	Read	List payouts with optional filters for status and date range.

Webhooks

Tool	Category	Description
`get_webhook`	Read	Retrieve a webhook endpoint by ID.
`list_webhooks`	Read	List all registered webhook endpoints.
`update_webhook`	Write	Update a webhook endpoint's URL or event subscriptions.
`enable_webhook`	Write	Re-enable a disabled webhook endpoint.
`disable_webhook`	Write	Disable an active webhook endpoint.

Events

Tool	Category	Description
`get_event`	Read	Retrieve an event by ID.
`list_events`	Read	List events with optional filters for type and date range.

Glossary

Term	Definition
MCP	Model Context Protocol — the open standard that defines how AI assistants connect to external tools and data sources.
MCP host	The AI environment that connects to the MCP server and presents results to you — for example, Claude.
MCP server	PayMongo's server-side implementation of MCP — the intermediary between your AI host and the PayMongo API.
Tool	A discrete action the MCP server exposes to the AI host, mapping to one or more PayMongo API operations.
Tool call	A single invocation of a tool by the AI host during a conversation.
Context	The parameters and information the AI host passes to the MCP server alongside a tool call.
Session	An active, authenticated connection between the AI host and the MCP server.
Read tool	A tool that retrieves data without modifying anything.
Write tool	A tool that triggers an action that modifies data — requires explicit confirmation before execution.
Livemode	Whether a session is operating against live or test data, determined by the API key used to authenticate.