Laravel Credo MCP

An MCP (Model Context Protocol) server for the Credo payment gateway, built on Laravel MCP and powered by zowesoft/laravel-credo.

Let any AI client — Claude Desktop, Cursor, Claude Code, Laravel Boost — verify Credo transactions and validate webhook signatures through natural language, using your app's configured Credo keys. Read-only by default; payment creation is available behind an explicit opt-in.

Requirements

• PHP 8.2+
• Laravel 11.45+, 12, or 13
• zowesoft/laravel-credo ^1.0 (installed automatically) with your CREDO_PUBLIC_KEY / CREDO_SECRET_KEY configured

Installation

composer require zowesoft/laravel-credo-mcp

The package registers a local (stdio) MCP server under the handle credo automatically. That's it.

Connecting an AI client

📖 Full walkthrough: Connect the Credo MCP server to Claude Desktop — including Windows/macOS config examples and how to enable the write gate safely.

Run the server with Laravel MCP's local server command:

php artisan mcp:start credo

Claude Desktop / Claude Code

Point your MCP client at the artisan command:

{
  "mcpServers": {
    "credo": {
      "command": "php",
      "args": ["/absolute/path/to/your/app/artisan", "mcp:start", "credo"]
    }
  }
}

Web (HTTP) servers

If you prefer to expose the server over HTTP, register it in your application's routes/ai.php:

use Laravel\Mcp\Facades\Mcp;
use ZoweSoft\LaravelCredoMcp\Servers\CredoServer;

Mcp::web('/mcp/credo', CredoServer::class)
    ->middleware(['auth:sanctum']); // protect it — it uses your live keys

Tools

verify-transaction

Verify a payment with Credo by its transaction reference (transRef).

Returns a structured summary: successful flag, human-readable status, amount, currency, fees, customer email, both references, payment method — and a matches_expectations checklist result when expectations are provided.

"Was order ORDER-1 actually paid?"
→ verify-transaction(reference: "VS-ABC123", expected_amount: 1500, expected_currency: "NGN")

verify-webhook-signature

Validate an inbound Credo webhook against your configured secret key.

Returns valid: true with the event type and a transaction summary, or a clear error when the signature does not match. Perfect for debugging webhooks.

"Is this Credo webhook payload legitimate?"
→ verify-webhook-signature(signature: "abc123...", payload: {...})

initialize-transaction (opt-in write tool)

Create a new Credo payment and get its checkout link. Disabled by default. The tool is only registered when the server is started with CREDO_MCP_ALLOW_WRITES=true, so read-only deployments never expose it to AI clients.

Returns the authorization_url to send the customer to, plus both transaction references and a suggested next step (verify server-side). Annotated destructiveHint so careful AI clients ask before using it.

"Create a ₦1,500 payment link for order ORDER-1"
→ initialize-transaction(amount: 1500.0, email: "buyer@example.com", reference: "ORDER-1")

Configuration

Publish the config file to customize:

php artisan vendor:publish --tag=laravel-credo-mcp-config

return [
    // Set CREDO_MCP_ENABLED=false to skip local server registration
    'enabled' => env('CREDO_MCP_ENABLED', true),

    // The local server handle (default: credo)
    'local_handle' => env('CREDO_MCP_LOCAL_HANDLE', 'credo'),

    // Set CREDO_MCP_ALLOW_WRITES=true to expose the initialize-transaction tool
    'allow_writes' => env('CREDO_MCP_ALLOW_WRITES', false),
];

The Credo keys, mode, retry and logging settings all come from zowesoft/laravel-credo — this package never handles keys itself and never sends them to the AI client.

Security notes

• Read-only by default. The only write tool, initialize-transaction, is invisible to AI clients unless you set CREDO_MCP_ALLOW_WRITES=true — and it cannot move money either; it only creates a checkout link that a customer must complete.
• Keys stay server-side. Keys are only used inside your Laravel app; they are never exposed to the model or the MCP client.
• Protect web servers. If you register the server over HTTP, put authentication middleware in front of it.

Testing

composer install
vendor/bin/pest

Changelog

See CHANGELOG and GitHub Releases.

Contributing

PRs welcome! Please run vendor/bin/pint and vendor/bin/pest before submitting.

License

MIT. See LICENSE.md.