DEV Community: Himansu Rawal

Designing APIs for AI Agents First: What the Model Context Protocol Taught Us

Himansu Rawal — Sun, 08 Mar 2026 14:56:55 +0000

The way we design developer APIs has been frozen in place for a decade. You define a REST contract, document it with OpenAPI, generate a client SDK, and call it done. That paradigm was built for a specific kind of consumer: a human developer who reads docs, reasons about state, and writes code to interact with your system.

That paradigm is ending.

The Model Context Protocol (MCP) forced us to rethink every API design assumption we had at PayArk. What we built as a result changed how we think about the entire surface area of our platform — not just the AI integration layer.

1. What MCP Actually Is (And What It Isn't)

MCP is a specification — championed by Anthropic and adopted by Claude, Cursor, and others — that defines a standardized interface for AI systems to interact with external tools and data sources. At its core, it is deceptively simple: an AI agent calls a "tool," a function with defined input parameters, and receives a structured output. The agent then uses that output to reason about its next step.

This sounds like function-calling. It is not.

The critical distinction is the contract surface. Traditional function-calling is closed: the developer hardcodes the available tools for each specific AI interaction. MCP is open: the AI agent can dynamically discover, introspect, and reason about available tools at runtime. This changes the fundamental design question from "what do I need this agent to do?" to a far more consequential one: what should this system be able to expose?

2. The Fundamental API Design Problem: Humans vs. Agents

Human-first APIs are designed for comprehension. Endpoints are named intuitively, responses can be verbose, and inconsistency is acceptable as long as docs explain the exception.

Agents are different consumers. They don't "read" APIs — they pattern-match structured inputs and outputs against a reasoning graph built from your tool description strings. This imposes rigid requirements that are nearly invisible when building for human consumers.

Consider a standard REST endpoint we had at PayArk:

GET /v1/payments?project_id=proj_abc&status=success&page=2

For a human developer, this is perfectly clear. For an MCP agent, this single endpoint creates an ambiguity explosion. The agent doesn't know the range of valid status values. It doesn't know the pagination scheme. It doesn't know that project_id is required. It can only guess from the description field we provide — and if that description is incomplete, it will call the tool wrong.

After integrating MCP, we identified three core design pillars that separate agent-friendly APIs from the rest.

3. Pillar One: Atomicity Over Composability

Human developers love composable, chainable APIs. Agents cannot compose reliably — they will sometimes take shortcuts, hallucinate intermediate steps, or misinterpret how two separate API calls relate to each other.

For PayArk's MCP server, we rewrote our exposure surface to be atomic: each tool does exactly one thing and returns exactly one decisive result. Instead of exposing "list payments" and "get payment details" as two separate tools requiring the agent to chain calls, we built a single get_payment_analysis tool that accepts a payment ID and returns the full enriched record.

More calls. More round-trips. But zero ambiguity.

4. Pillar Two: Description Strings Are Your Real API

In traditional REST, your API contract is the schema. In MCP, your API contract is the natural language description string attached to every tool and parameter. This is not documentation you write after the fact. It is runtime contract enforcement.

Our tool descriptions are now written with surgical precision. A poorly written description like "gets payments" is a reliability failure. Our actual production description reads:

"Retrieves a single PayArk payment by its ID. Use this tool when you need to diagnose a failed transaction, look up the status of a specific charge, or investigate a webhook delivery failure. Requires a valid payment ID in the format pay_xxxxx. Do not use this for listing multiple payments."

The last sentence is critical. Without explicit negative-scope definitions, agents will attempt to use a single-resource tool like a collection endpoint.

5. Pillar Three: Errors Are Reasoning Inputs

A human reads a 404 response and goes to fix their code. An agent reads a 404 response and attempts to self-correct at runtime. This distinction completely changes how you should design error responses.

PayArk's MCP error responses now include a suggested_action field alongside the standard message:

{
  "error": "not_found_error",
  "message": "Payment pay_xyz was not found.",
  "suggested_action": "Verify the ID by calling list_payments with the relevant project_id first."
}

This single addition reduced agent hallucinations — where the model fabricates a plausible-looking payment ID to retry — by making the recovery path explicit.

6. What REST Gets Wrong for Agents (And What to Keep)

REST was never the problem. Loose REST was the problem. The agent-first constraints MCP imposed actually made our REST API better for human developers too. Atomic endpoints are easier to test. Precise description strings are better documentation. Structured errors give human developers the exact same decision-tree benefit they give AI agents.

The hidden lesson of MCP is that designing for the hardest consumer — an AI agent that cannot ask clarifying questions, cannot read between the lines, and cannot tolerate ambiguity — produces APIs with a level of rigor that benefits every consumer downstream.

7. The Future of the Financial API Surface

PayArk exposes the following MCP tools in production today:

Tool	Purpose
`list_projects`	Enumerate merchant project IDs and metadata
`get_payment`	Retrieve enriched records with diagnostic context
`list_payments`	Paginated query with explicit filter parameters
`create_payment_link`	Generate hosted checkout URL from natural language input
`get_subscription_status`	Return full lifecycle state with renewal date

We are building toward fully autonomous billing agents: AI systems that can detect a past_due subscription, generate a renewal link, and dispatch a personalized follow-up — all triggered from a single instruction to a Claude or Cursor agent with access to our MCP server.

The era of developers as the sole consumers of APIs is closing. The platforms that win the next cycle are the ones designing infrastructure that machines can reason about just as fluently as humans.

Links:

Site: payark-public-demo.vercel.app
MCP Docs: github.com/Payark-Inc

Engineering PayArk: Building High-Integrity Payment Rails at the Edge

Himansu Rawal — Sun, 08 Mar 2026 14:54:37 +0000

1. The "Pain" of Financial Integration in Nepal

Digital payment integration in Nepal has historically been an exercise in technical debt. Developers integrating legacy providers like eSewa and Khalti frequently find themselves mired in messy XML/form logic and manual verification flows. These systems often function as bespoke wrappers rather than unified services, forcing engineers to write fragmented verify logic for every individual carrier.

PayArk was built to solve the integration headache by providing a single, high-integrity API layer that abstracts this complexity into a deterministic, developer-first experience. We identified three primary friction points currently stifling innovation in the region:

Documentation Fragmentation — Outdated integration guides and non-standardized API behaviors lead to inconsistent production environments.
Lack of Type Safety — Relying on unstructured data and manual form-handling introduces runtime failures that are nearly impossible to debug at scale.
Inconsistent Callback Mechanisms — Variations in how transactional responses are handled create a state of "try/catch hell," threatening the transactional integrity required for serious financial systems.

2. The Hyper-Scale Edge Mesh: Cloudflare, Hono, and Bun

To achieve the performance required for modern commerce, PayArk utilizes an Edge Gateway architecture. By moving logic to the global perimeter, we achieve sub-10ms latency, ensuring that orchestration occurs as close to the user and the financial provider as possible.

Core Infrastructure Stack

Layer	Technology	Purpose
Edge Execution	Cloudflare Workers	Global execution layer for low-latency routing and session management
API Framework	Hono	High-performance middleware and request routing at the edge
Runtime & Tooling	Bun	Fast development runtime and automated CI/CD security gates
Realtime Hub	Durable Objects	State management and WebSocket coordination for live event streams

Every successful response is wrapped in a standardized envelope providing a trace_id and timestamp. To ensure industrial reliability, we implement RFC 7807 for machine-readable error specifications. Our gateway returns specific error types — such as validation-error, unauthorized, rls-violation, and rate-limited — to allow both human developers and AI agents to handle failures with precision.

3. The Industrial Specification: Functional Orchestration via Effect-TS

Internal orchestration at PayArk is governed by Effect-TS. This transition from "try/catch hell" to functional orchestration treats failures as first-class citizens, providing three core benefits:

Unified Error Handling — Every failure is a strongly-typed value, eliminating ambiguous catch-all exceptions.
Micro-Retries with Idempotency — We utilize an Idempotency-Key header on all mutating requests. This ensures that even during jittered retries, payments are never accidentally duplicated.
Traceability — Every Effect is tagged with a unique Trace-ID, providing 100% observability from the edge gateway through to the transaction layer.

To prevent Thundering Herd scenarios where simultaneous retries DDoS a carrier's API, we implement a jittered exponential backoff strategy:

const retrySchedule = Schedule.exponential(100, 2).pipe(
  Schedule.jittered,
  Schedule.compose(Schedule.recurs(5))
);

4. Zero-Trust Security: Defense-in-Depth at the Application Layer

PayArk operates on a Defense-in-Depth principle, securing the application layer with the same rigor as the network perimeter.

App-Layer Encryption (ALE) — Sensitive provider secrets are never stored in cleartext. They are sealed via AES-256-GCM before database insertion. The Master Pepper key is isolated as a Cloudflare Worker Secret, ensuring it is never exposed in the database or source control.
Postgres Row-Level Security (RLS) — We enforce strict multi-tenant isolation at the database level. Every query automatically verifies the project_id against the authenticated user's scope.
Audit Logs — All platform activity is logged to Supabase, providing a persistent, observable integrity trail.
SSRF Egress Validation — Merchant-defined return_url values are resolved through a strict allow-list and checked against RFC 1918 private IP ranges before any outbound connection is established.

5. NRB-Compliant Push-Based Subscriptions

In Nepal, regulatory directives from the Nepal Rastra Bank (NRB) restrict automated "Pull" deductions for local wallets. PayArk solves this for the SaaS ecosystem through a Push-Based Subscription model.

Subscription Lifecycle

Customer Initiation — Customers explicitly authorize each period's payment via a hosted portal.
Edge Cron Orchestration — Our engine generates renewal reminders and manages status transitions across tiers: active, past_due, and canceled.
Permanent Links — Every subscription includes a permanent hosted link (payark.io/sub/:id) where users can self-serve renewals at any time.

From this stream, we derive precise enterprise analytics. MRR is calculated as the sum of all active subscription amounts normalized to 30 days, while ARR and churn rates are generated directly from the Postgres transaction stream.

6. AI-Native Developer Experience & The Model Context Protocol (MCP)

PayArk is built for engineers who value a high-end IDE experience. We have eliminated the Webhook Tunneling Tax by utilizing Cloudflare Durable Objects to map edge event streams directly to a developer's local endpoint.

The PayArk CLI and the payark listen command forward live webhooks to your local machine with sub-10ms latency, eliminating the need for external tools like ngrok.

We are also the first platform in the region to support the Model Context Protocol (MCP), allowing AI agents like Claude or Cursor to interact directly with your infrastructure via tools like:

list_projects — Identify project scopes and IDs.
list_payments / get_payment — Analyze transaction states and failure reasons.
create_payment_link — Generate checkout URLs via natural language.

Our Zero-Dependency SDK is isomorphic and tree-shakeable, built to run flawlessly across Node 18+, Bun, and Deno.

7. Heuristic Resilience: Solving the "Double-Question-Mark" Bug

A prime example of our Resilient Orchestration is how we handle carrier-side protocol violations. The eSewa callback mechanism frequently appends ?data=PAYLOAD to merchant return URLs without checking for existing query parameters. This creates malformed URIs (e.g., ?payment_id=abc?data=xyz) that violate RFC 3986 and break standard database lookups.

We implemented a defensive sniffer in the Edge Gateway to normalize these violations before they reach the business logic:

// Detect and correct eSewa's URI violation (RFC 3986)
if (!dataParam && payment_id?.includes("?data=")) {
  const [cleanId, cleanData] = payment_id.split("?data=");
  payment_id = cleanId;
  dataParam = cleanData;
}

8. Conclusion: The Future of Fintech in Nepal

The PayArk mission is to move financial infrastructure in Nepal away from legacy integration headaches and toward a system that feels like high-end AI-native infrastructure — transparent, predictable, and resilient. By bridging the gap between fragmented local systems and modern edge-native standards, we are providing the high-integrity rails required for the next generation of SaaS in the region.

PayArk is built for engineers, by engineers, because the future of money depends on systems that just work.

Links:

Site: payark-public-demo.vercel.app
GitHub: github.com/Payark-Inc