Daraja MCP Server

A self-hosted MCP server for Safaricom M-Pesa (Daraja) APIs, deployed on Cloudflare Workers. You clone it, add your own Daraja credentials, deploy to your own Cloudflare account, and connect your AI tools to it.

If you are an LLM consumer: read llm.txt first and treat it as the primary integration contract.

Who Is This For?

This server is designed to be self-hosted. There is no shared hosted instance — each user deploys their own.

Audience	What You Get
Developers building AI-powered apps	Deploy this to your Cloudflare account, connect your AI assistant (VS Code Copilot, Claude, Cursor), and your agent can initiate M-Pesa payments, check statuses, and debug errors without you writing glue code.
Teams shipping M-Pesa integrations	Use this as your payment backend for AI agents — customer support bots, checkout assistants, or automation workflows that need to trigger and verify payments.
Solo developers exploring MCP	Fork, deploy to sandbox with test credentials, and experiment with how AI tools interact with real payment APIs in a safe environment.

Deployment Model

You (developer)
  ├── Clone this repo
  ├── Add your Daraja credentials (consumer key, secret, passkey)
  ├── Deploy to YOUR Cloudflare account (free tier works)
  └── Connect your AI tools to YOUR worker URL

Each deployment is isolated. Your credentials, KV data, rate limits, and transaction logs belong entirely to you. Nobody else can access your instance.

Start Here (Beginner Friendly)

If you are new to MCP, read this first:

In simple terms, this project lets an AI assistant safely do common M-Pesa payment tasks through structured tools.

What Is an MCP Server?

MCP (Model Context Protocol) is a standard way for AI assistants to call tools.

An MCP server is a service that:

defines tools with clear input/output rules
receives tool calls from AI clients
executes real business actions
returns structured responses

In this project, the tools are payment-focused actions like starting STK push and checking transaction status.

Why This Server Is Useful

Without this server, teams often hardcode payment logic inside chatbot prompts or app glue code.

This server gives you:

reusable payment tools any MCP-compatible client can call
safer operations via API key auth and rate limits
reliable transaction traceability in KV logs
cleaner separation between AI behavior and payment infrastructure

Typical Use Cases

AI customer support can trigger STK push after user confirmation.
AI checkout assistant can verify if a payment completed.
Operations assistant can explain Daraja error codes quickly.
Developers can simulate payment flows in sandbox without real charge.

How It Works (High Level)

Your AI client sends a tool call to this server at /mcp.
The server validates auth and usage limits.
The selected tool runs Daraja API logic.
Results are returned as structured JSON for the AI client.
Callback updates and transaction metadata are stored in KV.

Architecture Diagram

flowchart LR
  A[AI Client] -->|MCP call| B[Daraja MCP Server]
  B --> C[Auth and Rate Limit]
  B --> D[Tool Handlers]
  D --> E[Daraja API]
  D --> F[Cloudflare KV]
  E --> G["/callback endpoint"]
  G --> F

For full architecture, sequence diagrams, and examples, see docs/ARCHITECTURE.md.

For detailed setup across MCP consumers (VS Code, stdio-first hosts, and custom clients), see docs/MCP_CONSUMERS.md.

Usage Examples

List tools:

curl -H "x-api-key: <your_api_key>" https://<your-domain>/mcp/tools

Health check:

curl https://<your-domain>/health

See end-to-end illustrations and tool input/output examples in docs/ARCHITECTURE.md.

Quick Start in 5 Minutes

Install dependencies: npm install
Create local vars template: npm run setup:local
Fill real values in .dev.vars
Validate config: npm run doctor
Start local server: npm run dev
Check health: GET /health

If you want a strict config check that fails on missing required values, run: npm run doctor -- --strict

Beginner Learning Links

Legend: Beginner = no prior MCP knowledge needed. Intermediate = some prior context helps.

MCP fundamentals:

MCP introduction (Beginner, ~10 min): https://modelcontextprotocol.io/introduction
MCP architecture concepts (Beginner, ~15 min): https://modelcontextprotocol.io/docs/learn/architecture
MCP specification (Intermediate, ~20-30 min skim): https://spec.modelcontextprotocol.io/

Cloudflare basics for this project:

Cloudflare Workers overview (Beginner, ~10 min): https://developers.cloudflare.com/workers/
Wrangler CLI docs (Beginner, ~15 min): https://developers.cloudflare.com/workers/wrangler/
Workers KV getting started (Beginner, ~15 min): https://developers.cloudflare.com/kv/get-started/
Workers bindings overview (Intermediate, ~15 min): https://developers.cloudflare.com/workers/runtime-apis/bindings/

Daraja and M-Pesa docs:

Safaricom developer portal (Beginner, ~5 min): https://developer.safaricom.co.ke/
Daraja APIs catalog (Beginner, ~10 min): https://developer.safaricom.co.ke/apis
Daraja Getting Started (Beginner, ~15 min): https://developer.safaricom.co.ke/apis/GettingStarted
Daraja Authorization OAuth (Intermediate, ~10 min): https://developer.safaricom.co.ke/apis/Authorization

MCP clients and tooling:

Use MCP servers in VS Code (Beginner, ~15 min): https://code.visualstudio.com/docs/copilot/chat/mcp-servers
MCP configuration in VS Code (Intermediate, ~15 min): https://code.visualstudio.com/docs/copilot/reference/mcp-configuration

Diagrams and visuals:

Mermaid intro (Beginner, ~10 min): https://mermaid.js.org/intro/
Mermaid live editor (Beginner, hands-on): https://mermaid.live/edit

Current Status

Implemented: Commit 1 - Project Bootstrap, Commit 2 - MCP Server Setup, Commit 3 - API Key Auth, Commit 4 - Rate Limiting (KV), Commit 5 - OAuth Token (Daraja), Commit 6 - STK Push, Commit 7 - Transaction Status, Commit 8 - Payment Verification Layer, Commit 9 - Callback Handler, Commit 10 - Simulation Tool, Commit 11 - Error Intelligence, Commit 12 - Workers AI Integration, Commit 13 - Logging + Observability, Commit 14 - Agents Integration (Future)

Cloudflare Worker project scaffold
Basic fetch handler
Health endpoint: GET /health
MCP SDK integrated (@modelcontextprotocol/sdk)
MCP server configured as daraja-mcp-server v1.1.0
Basic tool registration with initial get_usage_status tool
MCP transport endpoint: /mcp
Tool discovery endpoint: GET /mcp/tools
API key auth middleware for protected routes via x-api-key
KV-backed daily rate limiting middleware (USAGE namespace)
Request limit: 50 requests per UTC day
Daraja OAuth token tool: get_access_token
Token caching in KV (TOKENS namespace)
STK Push tool: stk_push
Daraja STK password generation: Base64(shortCode + passkey + timestamp)
STK request/response logging in KV (TRANSACTIONS namespace)
Transaction status tool: check_transaction_status
Normalized response fields: status, resultCode, responseCode, isComplete
Payment verification tool: verify_payment_intent
Verification checks: amount matching and optional phone matching
Callback endpoint: POST /callback
Callback payload storage in KV (CALLBACKS namespace)
Development simulation tool: simulate_payment (no external API calls)
Daraja error explanation tool: explain_error_code
Transaction log summary tool: summarize_transaction_logs
Optional Workers AI enhancement for natural language summaries
Structured request and error logging utilities
DEBUG_MODE=true enables request/error log emission
Orchestration planning tool: orchestrate_payment_workflow
Provides agent-to-agent payment workflow plans for future Cloudflare Agents runtime

Authentication

Protected routes require header: x-api-key: <your_api_key>
Public route: GET /health

Set API key secret before deploy:

wrangler secret put API_KEY

Rate Limiting (KV)

Create a KV namespace and bind it as USAGE in your wrangler.toml:

[[kv_namespaces]]
binding = "USAGE"
id = "<your-usage-kv-namespace-id>"
preview_id = "<your-usage-kv-preview-id>"

If the daily quota is exhausted, protected endpoints return 429.

Daraja OAuth

Required secrets:

wrangler secret put DARAJA_CONSUMER_KEY
wrangler secret put DARAJA_CONSUMER_SECRET

Optional secrets/vars:

DARAJA_ENV = sandbox (default) or production
DARAJA_BASE_URL = custom override for Daraja base URL

Add token cache KV binding in wrangler.toml:

[[kv_namespaces]]
binding = "TOKENS"
id = "<your-tokens-kv-namespace-id>"
preview_id = "<your-tokens-kv-preview-id>"

STK Push

Required configuration:

wrangler secret put DARAJA_SHORTCODE
wrangler secret put DARAJA_PASSKEY
wrangler secret put DARAJA_CALLBACK_URL

Important notes:

A callback endpoint is required for end-to-end STK flow because final payment outcomes are sent asynchronously by Daraja.
This server already implements the callback route at POST /callback.
Set DARAJA_CALLBACK_URL to a real public HTTPS URL, for example https:///callback.
For sandbox, use the Lipa Na M-Pesa Online passkey for shortcode 174379. Do not use Security Credential for STK password generation.
STK password formula is Base64(shortCode + passkey + timestamp), where timestamp format is YYYYMMDDHHmmss.

Optional:

DARAJA_TRANSACTION_TYPE = CustomerPayBillOnline (default) or CustomerBuyGoodsOnline

Add transaction log KV binding in wrangler.toml:

[[kv_namespaces]]
binding = "TRANSACTIONS"
id = "<your-transactions-kv-namespace-id>"
preview_id = "<your-transactions-kv-preview-id>"

stk_push input fields:

amount
phoneNumber
accountReference
transactionDesc
callbackUrl (optional override)
transactionType (optional override)

Set your Daraja callback to this endpoint:

https://<your-worker-domain>/callback

The callback endpoint stays unauthenticated by design so Safaricom can deliver payment updates.

Add callback storage KV binding in wrangler.toml:

[[kv_namespaces]]
binding = "CALLBACKS"
id = "<your-callbacks-kv-namespace-id>"
preview_id = "<your-callbacks-kv-preview-id>"

Run Locally

Quick local setup:

npm run setup:local
npm install
npm run doctor

The doctor command checks required Daraja and API key variables before starting the worker. Use npm run doctor -- --strict when you want missing required keys to fail fast.

npm install
npm run dev

Test (TDD)

npm test

Test Coverage Report

Install coverage tooling (if starting from a minimal setup):

npm install --save-dev vitest @vitest/coverage-v8

Generate coverage output:

npx vitest run --coverage

Generate and refresh coverage report in README:

npm run coverage:update

Last updated: 2026-03-22T00:35:43.569Z

Metric	Coverage	Covered	Total
Statements	80.69%	347	430
Branches	61.98%	225	363
Functions	84.50%	60	71
Lines	80.42%	337	419

Refresh with: npm run coverage:update

Codecov CLI Upload (Manual, Local OS)

Codecov upload is intentionally done outside CircleCI in this repository.

Best method for this project: manual local upload after coverage generation, to keep CI lean and avoid token handling in pipeline jobs.

If you later choose CI-based upload, use the same verified CLI flow in your CI runner and keep CODECOV_TOKEN only in CI secrets.

Recommended flow:

Generate coverage: npx vitest run --coverage
Verify and install Codecov CLI for your OS
Upload with token:

./codecov upload-process -t "$CODECOV_TOKEN" -f coverage/coverage-final.json -F vitest

Windows (PowerShell):

$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest -Uri https://keybase.io/codecovsecurity/pgp_keys.asc -OutFile codecov.asc
gpg.exe --import codecov.asc

Invoke-WebRequest -Uri https://cli.codecov.io/latest/windows/codecov.exe -OutFile codecov.exe
Invoke-WebRequest -Uri https://cli.codecov.io/latest/windows/codecov.exe.SHA256SUM -OutFile codecov.exe.SHA256SUM
Invoke-WebRequest -Uri https://cli.codecov.io/latest/windows/codecov.exe.SHA256SUM.sig -OutFile codecov.exe.SHA256SUM.sig

gpg.exe --verify codecov.exe.SHA256SUM.sig codecov.exe.SHA256SUM
if ((Compare-Object -ReferenceObject ((($(certUtil -hashfile codecov.exe SHA256)[1]), 'codecov.exe') -join '  ') -DifferenceObject (Get-Content codecov.exe.SHA256SUM)).Length -eq 0) {
  Write-Output 'SHASUM verified'
} else {
  exit 1
}

.\codecov.exe upload-process -t "$env:CODECOV_TOKEN" -f coverage/coverage-final.json -F vitest

Linux:

curl https://keybase.io/codecovsecurity/pgp_keys.asc | gpg --no-default-keyring --keyring trustedkeys.gpg --import
curl -Os https://cli.codecov.io/latest/linux/codecov
curl -Os https://cli.codecov.io/latest/linux/codecov.SHA256SUM
curl -Os https://cli.codecov.io/latest/linux/codecov.SHA256SUM.sig
gpg --verify codecov.SHA256SUM.sig codecov.SHA256SUM
shasum -a 256 -c codecov.SHA256SUM
sudo chmod +x codecov
./codecov upload-process -t "$CODECOV_TOKEN" -f coverage/coverage-final.json -F vitest

macOS:

curl https://keybase.io/codecovsecurity/pgp_keys.asc | gpg --no-default-keyring --keyring trustedkeys.gpg --import
curl -Os https://cli.codecov.io/latest/macos/codecov
curl -Os https://cli.codecov.io/latest/macos/codecov.SHA256SUM
curl -Os https://cli.codecov.io/latest/macos/codecov.SHA256SUM.sig
gpg --verify codecov.SHA256SUM.sig codecov.SHA256SUM
shasum -a 256 -c codecov.SHA256SUM
sudo chmod +x codecov
./codecov upload-process -t "$CODECOV_TOKEN" -f coverage/coverage-final.json -F vitest

CircleCI CI/CD

This repository now includes CircleCI pipeline config at .circleci/config.yml.

Pipeline behavior:

CI on branches and tags:
- npm run check
- npm test
- npm run test:e2e
- npm run test:coverage
- coverage artifacts stored in CircleCI
- Codecov upload via CircleCI Codecov orb (codecov/codecov@5)
CD to sandbox on main branch.
Production deployment is intentionally disabled in CircleCI.
Smoke tests are currently disabled in the workflow.

Required CircleCI environment variables:

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID

Required runtime secret variables for sandbox deploy (auto-synced to Worker secrets):

SANDBOX_API_KEY -> API_KEY
SANDBOX_DARAJA_CONSUMER_KEY -> DARAJA_CONSUMER_KEY
SANDBOX_DARAJA_CONSUMER_SECRET -> DARAJA_CONSUMER_SECRET
SANDBOX_DARAJA_SHORTCODE -> DARAJA_SHORTCODE
SANDBOX_DARAJA_PASSKEY -> DARAJA_PASSKEY
SANDBOX_DARAJA_CALLBACK_URL -> DARAJA_CALLBACK_URL

Required sandbox KV namespace variables for deploy config generation:

SANDBOX_USAGE_KV_ID
SANDBOX_USAGE_KV_PREVIEW_ID
SANDBOX_TOKENS_KV_ID
SANDBOX_TOKENS_KV_PREVIEW_ID
SANDBOX_TRANSACTIONS_KV_ID
SANDBOX_TRANSACTIONS_KV_PREVIEW_ID
SANDBOX_CALLBACKS_KV_ID
SANDBOX_CALLBACKS_KV_PREVIEW_ID

Optional sandbox runtime variables:

SANDBOX_DARAJA_ENV -> DARAJA_ENV
SANDBOX_DARAJA_BASE_URL -> DARAJA_BASE_URL
SANDBOX_DARAJA_TRANSACTION_TYPE -> DARAJA_TRANSACTION_TYPE

Use the "Codecov CLI Upload (Manual, Local OS)" section above when you need local/manual upload.

Required Codecov variable in CircleCI:

CODECOV_TOKEN

Pre-commit Hook

This repository uses Husky pre-commit hooks.

Hook file: .husky/pre-commit
Runs before each commit:
- npm run check
- npm test

Deploy

For security, wrangler.toml does not store real KV namespace IDs. Generate a temporary deploy config from environment variables and deploy using that generated file.

Example (PowerShell):

$env:SANDBOX_USAGE_KV_ID="<kv-id>"
$env:SANDBOX_USAGE_KV_PREVIEW_ID="<kv-preview-id>"
$env:SANDBOX_TOKENS_KV_ID="<kv-id>"
$env:SANDBOX_TOKENS_KV_PREVIEW_ID="<kv-preview-id>"
$env:SANDBOX_TRANSACTIONS_KV_ID="<kv-id>"
$env:SANDBOX_TRANSACTIONS_KV_PREVIEW_ID="<kv-preview-id>"
$env:SANDBOX_CALLBACKS_KV_ID="<kv-id>"
$env:SANDBOX_CALLBACKS_KV_PREVIEW_ID="<kv-preview-id>"

node scripts/generate-wrangler-sandbox-config.mjs
npx wrangler deploy --name daraja-mcp-server-sandbox -c .wrangler.sandbox.toml

npm run deploy

Release Runbook

Use the production checklist in docs/RELEASE_RUNBOOK.md for:

pre-release validation (npm run check, tests, Terraform validate)
Cloudflare secrets and bindings verification
deployment sequence (terraform apply and npm run deploy)
post-deploy smoke tests for /health, /mcp/tools, and callback routing

Release governance documents:

Health Check Response

GET /health

{
  "ok": true,
  "service": "daraja-mcp-server",
  "status": "healthy",
  "timestamp": "2026-03-22T00:00:00.000Z"
}

Integrate with Your AI Tool

After deploying to your own Cloudflare account, connect your AI coding assistant or production agent to your Worker URL.

For developers: Point your IDE's MCP client at your deployed server so your AI assistant can test M-Pesa flows, debug error codes, and verify transactions — no context-switching to Postman or writing throwaway scripts.

For production AI agents: Connect your chatbot, customer support agent, or automation workflow so it can initiate payments, check status, and handle M-Pesa operations on behalf of real users.

Copy-paste config templates are in examples/:

Platform	Config File	Setup
VS Code (Copilot Chat)	`examples/vscode-mcp.json`	Copy to `.vscode/mcp.json`
Claude Code	`examples/claude-code-mcp.json`	Copy to `.mcp.json` or `claude mcp add`
Claude Desktop	`examples/claude-desktop-config.json`	Merge into `claude_desktop_config.json`
Cursor	`examples/cursor-mcp.json`	Copy to `.cursor/mcp.json`
Windsurf	`examples/windsurf-mcp.json`	Add via Windsurf MCP settings
OpenAI Codex	`examples/codex-consumer-config.toml`	Add to `.codex/config.toml`

All templates use https://<your-domain>/mcp — replace with your deployed Worker URL.

For detailed setup instructions per platform, see docs/MCP_CONSUMERS.md.

Using with OpenAI Codex

This project is fully configured for OpenAI Codex (CLI, IDE extension, and Codex app).

Quick Start

npm install -g @openai/codex
cd daraja_mcp_server
codex

Codex automatically reads AGENTS.md and loads project-scoped configuration from .codex/config.toml.

What's Included

Component	Location	Purpose
`AGENTS.md`	Root	Project context, conventions, commands
`.codex/config.toml`	Project	MCP servers, agent config, skills
`.codex/agents/`	Project	Custom agent definitions (6 agents)
`.agents/skills/`	Project	Reusable workflow skills (6 skills)
`.codex/PLANS.md`	Project	Planning template for complex tasks
`.codex/code_review.md`	Project	Review standards reference
`docs/CODEX_GUIDE.md`	Docs	Full Codex usage guide

Multi-Agent Workflows

# Full codebase analysis
Analyze this codebase. Spawn codebase_analyst, reviewer, and pr_explorer in parallel.

# PR review
Review this branch against main with security, correctness, and test coverage agents.

# TDD implementation
$tdd-workflow — Fix [describe issue] with full TDD.

See docs/CODEX_GUIDE.md for complete workflow documentation.

Name		Name	Last commit message	Last commit date
Latest commit History 74 Commits
.agents/skills		.agents/skills
.circleci		.circleci
.codex		.codex
.github		.github
.husky		.husky
docs		docs
examples		examples
infra/terraform		infra/terraform
scripts		scripts
src		src
tests		tests
.dev.vars.example		.dev.vars.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
README.md		README.md
llm.txt		llm.txt
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
wrangler.toml		wrangler.toml

Folders and files

Latest commit

History

Repository files navigation

Daraja MCP Server

Who Is This For?

Deployment Model

Start Here (Beginner Friendly)

What Is an MCP Server?

Why This Server Is Useful

Typical Use Cases

How It Works (High Level)

Architecture Diagram

Usage Examples

Quick Start in 5 Minutes

Beginner Learning Links

Current Status

Authentication

Rate Limiting (KV)

Daraja OAuth

STK Push

Run Locally

Test (TDD)

Test Coverage Report

Codecov CLI Upload (Manual, Local OS)

CircleCI CI/CD

Pre-commit Hook

Deploy

Release Runbook

Health Check Response

Integrate with Your AI Tool

Using with OpenAI Codex

Quick Start

What's Included

Multi-Agent Workflows

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages