Building API Integrations with Cursor Agent

The previous developer left a half-finished Stripe integration. The webhook handler swallows errors silently. The SendGrid email calls have no retry logic. The Twilio SMS code hard-crashes when the API rate-limits you. And now you need all three to work together: payment succeeds, receipt email sends, SMS confirmation follows — with proper error handling at every step. Your deadline is Friday.

Wiring up third-party APIs is one of the tasks where Cursor provides the most leverage. The AI has seen thousands of Stripe, SendGrid, and Twilio integrations and knows the common pitfalls — idempotency keys, webhook signature verification, exponential backoff — that take hours to get right manually. The workflow below shows you how to build a production-grade integration layer in a fraction of the time.

What You’ll Walk Away With

• A base integration class with built-in retry logic, circuit breakers, and structured error handling that you can reuse across every API provider
• Copy-paste prompts for analyzing unfamiliar API documentation and generating typed client code
• A webhook handler template with signature verification and replay attack protection
• A testing strategy that uses mock servers so your CI pipeline never makes real API calls
• Knowledge of when MCP servers replace custom integration code entirely

The Workflow

Step 1: Analyze the existing mess

Before writing new code, understand what the previous developer left behind. Use Ask mode to get a clear picture of the current state.

Tip

Copy-paste prompt — Integration audit:

@src/integrations @src/services @src/lib

Audit the existing API integration code and report:

1. Which APIs are integrated and what state is each in (complete, partial, broken)?
2. What error handling exists? Is it consistent across providers?
3. Are API keys stored securely (env vars, not hard-coded)?
4. Is there retry logic? If so, is it per-provider or generic?
5. Are webhook handlers verifying signatures?
6. What happens if an API call fails midway through a multi-step flow (payment + email + SMS)?
7. Are there any rate limiting protections?

Rate each integration: production-ready, needs-work, or dangerous.

Step 2: Design the integration architecture

Switch to Agent mode and create a solid foundation before implementing individual providers.

@src/integrations

Design and implement a base integration layer:

1. Create src/integrations/base-client.ts with:
   - Configurable retry with exponential backoff and jitter
   - Circuit breaker (open after 5 failures in 60 seconds, half-open after 30 seconds)
   - Request/response logging with sensitive data redaction
   - Timeout configuration per provider
   - Rate limit detection from response headers (Retry-After, X-RateLimit-Remaining)

2. Create src/integrations/types.ts with:
   - IntegrationError class with: provider, code, isRetryable, originalError
   - IntegrationConfig interface
   - CircuitBreakerState enum

3. Create src/integrations/errors.ts with specific error classes:
   - RateLimitError, AuthenticationError, ValidationError, TimeoutError, NetworkError

Do not implement any specific provider yet -- just the reusable foundation.

Step 3: Implement provider-specific clients

With the base layer in place, implement each provider by extending it. Reference the base class so Agent maintains consistency.

Tip

Copy-paste prompt — Stripe integration:

@src/integrations/base-client.ts @src/integrations/types.ts

Implement the Stripe payment integration at src/integrations/stripe-client.ts:

1. Extend BaseClient with Stripe-specific configuration
2. Implement createPaymentIntent, confirmPayment, refundPayment, and getPaymentStatus
3. Add idempotency key generation for all mutation operations
4. Handle Stripe-specific errors (card_declined, rate_limit, api_connection_error) and map to our error types
5. Parse rate limit headers and respect Retry-After
6. Add webhook signature verification using Stripe’s recommended approach (stripe.webhooks.constructEvent)
7. Type all parameters and return values — no any types

Use the stripe npm package. API version should be configurable via environment variable.

Repeat this pattern for SendGrid and Twilio, adjusting for each provider’s API specifics:

@src/integrations/base-client.ts @src/integrations/stripe-client.ts

Now implement SendGrid email integration at src/integrations/sendgrid-client.ts
following the same patterns as the Stripe client:

1. Extend BaseClient
2. Implement sendTransactionalEmail, sendBatchEmails, getEmailStatus
3. Handle SendGrid-specific errors (429 rate limit, 401 auth, 5xx server errors)
4. Support email templates with dynamic variables
5. Add bounce and complaint webhook handling
6. Log email send attempts with message IDs for traceability

Step 4: Build the orchestration layer

The real complexity is not in individual API calls — it is in coordinating them. When a payment succeeds but the email fails, what happens? You need a saga pattern or at minimum a reliable sequence with compensating actions.

Tip

Copy-paste prompt — Notification orchestration:

@src/integrations/stripe-client.ts @src/integrations/sendgrid-client.ts @src/integrations/twilio-client.ts

Create src/services/checkout-notification-service.ts that orchestrates the post-checkout flow:

1. After successful payment: send receipt email via SendGrid, then send SMS confirmation via Twilio
2. If email fails: log the failure, queue for retry, but do NOT fail the checkout — the payment already succeeded
3. If SMS fails: log and queue for retry, never fail the checkout over an SMS
4. Track the status of each step with a notifications table (payment_id, channel, status, attempt_count, last_error)
5. Implement a retry worker that processes the failed notifications queue every 60 seconds
6. Add a dead letter queue for notifications that fail after 5 attempts

The critical principle: the payment is the source of truth. Notification failures are degraded experience, not checkout failures.

Step 5: Secure the webhook handlers

Webhook endpoints are public-facing URLs that receive data from third-party services. Without proper security, anyone can forge webhook payloads.

@src/integrations

Create a secure webhook handler middleware at src/middleware/webhook-verify.ts:

1. Verify Stripe webhook signatures using the signing secret
2. Verify SendGrid event webhook signatures using their public key
3. Reject requests with timestamps older than 5 minutes (replay protection)
4. Parse the raw body (important: webhooks need the raw body for signature verification, not parsed JSON)
5. Log all webhook events with their verification status
6. Return 200 immediately to prevent retries, then process async
7. Handle duplicate deliveries idempotently (check event ID against a processed events table)

Add the webhook routes at src/app/api/webhooks/stripe/route.ts and src/app/api/webhooks/sendgrid/route.ts.

Step 6: Test without hitting real APIs

Tip

Copy-paste prompt — Integration test suite:

@src/integrations @src/services/checkout-notification-service.ts

Create a comprehensive test suite for the integration layer:

1. Set up msw (Mock Service Worker) to intercept all HTTP requests to Stripe, SendGrid, and Twilio APIs
2. Test the happy path: payment + email + SMS all succeed
3. Test partial failures: payment succeeds but email fails — verify checkout still succeeds and email is queued for retry
4. Test circuit breaker: simulate 5 consecutive Stripe failures and verify the circuit opens
5. Test rate limiting: return 429 with Retry-After header and verify the client waits before retrying
6. Test webhook signature verification: valid signature succeeds, tampered payload is rejected
7. Test idempotency: send the same payment request twice and verify only one charge is created

Use vitest. No real API calls should be made during tests.

Accelerating with MCP Servers

If you have MCP servers configured for services like GitHub, Linear, or Slack, Cursor’s Agent can use them directly as tools. This eliminates the need for custom integration code for supported operations.

For example, with the GitHub MCP server configured in .cursor/mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

Agent can directly create issues, read PRs, and manage repositories without you writing any GitHub API code. Use MCP servers for operational tasks (creating issues, posting messages) and custom integrations for core business flows (payment processing) where you need full control over error handling and retry logic.

When This Breaks

Rate limits in production despite local testing passing. Local tests with mock servers do not exercise real rate limits. Add rate limit counters to your integration layer that track calls per minute per provider. Set conservative limits (80% of the API’s stated limit) and queue excess requests.

Webhook events arrive out of order. Stripe can send payment_intent.succeeded before payment_intent.created in rare cases. Design your webhook handlers to be idempotent and order-independent. Use the event’s created timestamp, not arrival order, for sequencing.

Circuit breaker stays open too long. If the half-open check fails once, the circuit reopens for another 30 seconds. With a struggling API, this can mean minutes of downtime. Implement a sliding window: allow 1 in 10 requests through while in half-open state, increasing the ratio as successes accumulate.

Retry logic causes duplicate charges. Without idempotency keys, retrying a failed payment request that actually succeeded (but timed out) creates a double charge. Always use idempotency keys for mutation operations. Stripe, SendGrid, and most major APIs support them.

Test mocks drift from real API behavior. Mock servers only behave like the real API at the time you wrote the mocks. Periodically run your test suite against sandbox/test environments of the real APIs (not in CI, but as a scheduled job) to catch breaking changes.

What’s Next

Database Schema Design Design the data model that backs your integrations, including the notifications queue and webhook events table.

Security Audit Review your integration layer for security vulnerabilities: API key exposure, webhook forgery, injection attacks.

MCP Server Setup Configure MCP servers for the services you use most to eliminate boilerplate integration code.