Skip to content

An MCP Server for a SaaS API: Authentication, Pagination, and Rate Limits

A medium-scale AWS blueprint for exposing a SaaS API through MCP, with separate identity boundaries, safe pagination, layered rate limiting, and production operations.

Ekanatha Reddy Urivakili18 min3,458 words

1. Context and scale

An MCP server is an adapter between an MCP client—often an AI application—and an existing SaaS API. It should not turn the model into an API client with unbounded credentials. The server owns the integration boundary: it authenticates the caller, authorizes each tool, applies tenant and user limits, translates requests, and returns bounded results.

This blueprint exposes read-oriented customer and activity tools for a fictional SaaS product called Acme CRM. The MCP endpoint uses Streamable HTTP. The existing SaaS API uses OAuth 2.0 delegated grants, cursor pagination, and per-tenant quotas. The MCP service is deployed in AWS in one region across multiple Availability Zones.

Two credentials must remain distinct:

  • MCP access token: proves who the MCP caller is and what tools they may use.
  • SaaS access token: represents a user’s authorized connection to Acme CRM.

The MCP server validates the first and retrieves the second from its token store. It never asks a model to supply a SaaS bearer token, and it never returns either token in tool output.

The architecture is deliberately medium-sized: one TypeScript service, one relational database, a cache, and a queue. The queue handles background work such as token refresh and audit delivery; synchronous reads remain synchronous.

DimensionAssumption
Users30,000 daily users across 1,000 customer tenants
Requests20 requests/s average; 120 requests/s short peak across MCP calls
Data volume10 GB relational data, primarily connection metadata and audit records; SaaS business data remains upstream
Team size5 engineers across one platform/product team, with shared security and SRE support
Budget$4,000/month planning ceiling for this service’s AWS footprint, excluding SaaS vendor fees and shared corporate services

These are sizing assumptions, not measured capacity or vendor commitments. Load testing and AWS pricing for the target region must validate both the service limits and the cost envelope.

2. Requirements

Functional requirements:

IDRequirementAcceptance condition
F1Discover and invoke MCP tools over Streamable HTTPMCP clients can list tools and call supported tools
F2Authenticate MCP callersEvery protected request has a valid issuer, audience, expiry, and required scope
F3Connect a user to the SaaS APIDelegated SaaS credentials are stored and refreshed without exposing them to the model
F4Read SaaS data with paginationResults are bounded, and a continuation cursor can resume the same query
F5Enforce quotasPer-tenant and per-user limits apply before upstream calls
F6Audit accessTool name, tenant, principal, outcome, and request ID are recorded without secrets or sensitive payloads

Non-functional requirements:

AreaRequirementDesign response
AvailabilityProposed 99.9% monthly availability for MCP tool requests, excluding upstream SaaS outagesMulti-AZ tasks and database; upstream failures are surfaced as bounded tool errors
LatencyKeep adapter overhead low enough that the upstream API is the usual latency contributorAvoid unnecessary persistence on the request path; use connection pooling and bounded responses
SecurityTenant isolation and least-privilege delegated accessToken validation, tenant-scoped queries, encrypted token storage, tool-level authorization
ResilienceNo retry storm against a failing or throttled SaaS APIRate-limit reservations, bounded retries for safe reads, circuit breaker, Retry-After handling
OperabilityDiagnose failures across MCP, database, cache, queue, and SaaS callsCorrelated logs, traces, service and resource metrics, actionable alerts
MaintainabilityAdd tools without coupling protocol handling to SaaS detailsSeparate transport, application, and SaaS-adapter modules

3. High-level design

The public endpoint terminates TLS at an Application Load Balancer protected by AWS WAF. Fargate tasks host the MCP service in private subnets. The service validates MCP tokens against the configured issuer’s JWKS and checks tool scopes. SaaS OAuth callbacks pass through a dedicated application route, while the identity provider remains the authorization server. For deployments that need MCP OAuth authorization discovery or dynamic client registration, use an authorization server that explicitly supports the MCP authorization requirements; do not assume that any OIDC provider supplies those capabilities.

Aurora PostgreSQL stores connection metadata, tenant configuration, and audit outbox rows. SaaS access and refresh tokens are envelope-encrypted with AWS KMS before storage. ElastiCache for Redis provides short-lived cursor state if cursors are stateful, distributed quota counters, and circuit-breaker state. SQS carries refresh and audit-delivery work. Secrets Manager holds service secrets and encryption configuration, not per-user access tokens.

flowchart LR
    Client["MCP client"] --> WAF["AWS WAF"]
    WAF --> ALB["Application Load Balancer"]
    ALB --> ECS["Amazon ECS on Fargate"]
    ECS --> IdP["OAuth authorization server"]
    ECS --> SaaS["Acme CRM API"]
    ECS --> Redis["Amazon ElastiCache for Redis"]
    ECS --> DB["Amazon Aurora PostgreSQL"]
    ECS --> Queue["Amazon SQS"]
    Queue --> Worker["Fargate worker"]
    Worker --> DB
    ECS --> KMS["AWS KMS"]
    ECS --> Secrets["AWS Secrets Manager"]
    ECS --> Telemetry["CloudWatch and AWS X-Ray"]

The MCP service owns authorization and policy enforcement; the SaaS API remains the system of record for CRM data.

The public request path is intentionally small: validate caller, resolve tenant and SaaS connection, check quota, call the SaaS API, normalize a bounded result, and return it. Background workers do not execute model-requested business actions. Their responsibilities are limited to operational work such as refreshing tokens and delivering audit events.

4. Cloud service mapping

AWS is the selected deployment platform. Equivalents are illustrative service-category mappings, not claims of identical behavior.

ComponentAWS choiceAzure equivalentGCP equivalent
Edge filtering and ingressAWS WAF + Application Load BalancerAzure WAF + Application GatewayCloud Armor + external Application Load Balancer
Container runtimeAmazon ECS on AWS FargateAzure Container AppsCloud Run
Relational metadata storeAmazon Aurora PostgreSQLAzure Database for PostgreSQLCloud SQL for PostgreSQL
Distributed cacheAmazon ElastiCache for RedisAzure Managed RedisMemorystore for Redis
Background queueAmazon SQSAzure Service Bus queuesCloud Tasks or Pub/Sub, depending on delivery model
Encryption keysAWS KMSAzure Key VaultCloud KMS
Secret managementAWS Secrets ManagerAzure Key VaultSecret Manager
Logs and metricsAmazon CloudWatchAzure MonitorCloud Monitoring
Distributed tracingAWS X-Ray with OpenTelemetryApplication Insights with OpenTelemetryCloud Trace with OpenTelemetry
Container imagesAmazon ECRAzure Container RegistryArtifact Registry
Infrastructure identityECS task rolesManaged identitiesWorkload Identity

The code is portable TypeScript; the operational edges are not. The team should standardize on one cloud’s identity, networking, telemetry, and deployment conventions rather than attempt a multi-cloud abstraction at this scale.

5. Data design

Keep SaaS business records upstream. Persist only the state required to authorize and operate the integration. In particular, avoid a local mirror of customer data unless product requirements explicitly call for search, offline use, or analytics; a mirror creates synchronization, deletion, and consistency obligations.

The schema below assumes a tenant can have several user-linked SaaS connections. Application queries must scope every connection lookup by tenant and principal. The database constraint is a backstop, not a replacement for application authorization.

erDiagram
    TENANT ||--o{ PRINCIPAL : contains
    TENANT ||--o{ SAAS_CONNECTION : owns
    PRINCIPAL ||--o{ SAAS_CONNECTION : authorizes
    TENANT ||--o{ AUDIT_EVENT : records
    PRINCIPAL ||--o{ AUDIT_EVENT : performs
    TENANT {
        uuid id PK
        text name
        timestamptz created_at
    }
    PRINCIPAL {
        uuid id PK
        uuid tenant_id FK
        text issuer_subject
        timestamptz created_at
    }
    SAAS_CONNECTION {
        uuid id PK
        uuid tenant_id FK
        uuid principal_id FK
        text provider_subject
        bytea encrypted_token_bundle
        timestamptz expires_at
        timestamptz updated_at
    }
    AUDIT_EVENT {
        uuid id PK
        uuid tenant_id FK
        uuid principal_id FK
        text tool_name
        text outcome
        timestamptz created_at
    }

The database stores authorization relationships and encrypted credentials, not CRM customer records.

CREATE TABLE tenant (
    id uuid PRIMARY KEY,
    name text NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE principal (
    id uuid PRIMARY KEY,
    tenant_id uuid NOT NULL REFERENCES tenant(id),
    issuer_subject text NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now(),
    UNIQUE (tenant_id, issuer_subject),
    UNIQUE (tenant_id, id)
);

CREATE TABLE saas_connection (
    id uuid PRIMARY KEY,
    tenant_id uuid NOT NULL REFERENCES tenant(id),
    principal_id uuid NOT NULL,
    provider_subject text NOT NULL,
    encrypted_token_bundle bytea NOT NULL,
    encryption_key_id text NOT NULL,
    expires_at timestamptz NOT NULL,
    updated_at timestamptz NOT NULL DEFAULT now(),
    FOREIGN KEY (tenant_id, principal_id)
        REFERENCES principal(tenant_id, id),
    UNIQUE (tenant_id, principal_id, provider_subject)
);

CREATE TABLE audit_event (
    id uuid PRIMARY KEY,
    tenant_id uuid NOT NULL REFERENCES tenant(id),
    principal_id uuid,
    tool_name text NOT NULL,
    outcome text NOT NULL,
    request_id text NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX audit_event_tenant_created_idx
    ON audit_event (tenant_id, created_at DESC);

CREATE INDEX saas_connection_principal_idx
    ON saas_connection (tenant_id, principal_id);

encrypted_token_bundle contains an envelope-encrypted token payload; the encryption key identifier supports key rotation. Do not put access tokens, refresh tokens, cursor contents, or full CRM responses in audit_event. For reliable audit delivery, write the event and an outbox record in the same database transaction, then publish asynchronously. Retain audit rows according to the organization’s retention policy, not an arbitrary indefinite default.

6. Low-level design

The service has four main modules:

  • HTTP and MCP transport: negotiates protocol transport and attaches a validated caller context.
  • Application layer: authorizes the tool, applies quotas, resolves a SaaS connection, and defines result limits.
  • SaaS adapter: handles OAuth token refresh, HTTP timeouts, safe retries, vendor error mapping, and vendor pagination.
  • Infrastructure adapters: PostgreSQL, Redis, KMS, SQS, and telemetry implementations behind interfaces.
classDiagram
    class McpTransport {
        +handleRequest(request)
    }
    class ToolService {
        +searchCustomers(input, caller)
    }
    class AuthorizationPolicy {
        +requireScope(caller, scope)
        +requireTenantAccess(caller, tenantId)
    }
    class RateLimiter {
        +reserve(tenantId, principalId, tool)
    }
    class SaaSClient {
        +searchCustomers(query, pageToken)
        +refreshToken(connection)
    }
    class ConnectionStore {
        +getForPrincipal(tenantId, principalId)
        +saveTokens(connection)
    }
    class CursorCodec {
        +encode(claims)
        +decode(cursor, caller, queryHash)
    }
    McpTransport --> ToolService
    ToolService --> AuthorizationPolicy
    ToolService --> RateLimiter
    ToolService --> SaaSClient
    ToolService --> ConnectionStore
    ToolService --> CursorCodec

Interfaces keep protocol concerns separate from SaaS behavior and cloud persistence.

A minimal runnable example demonstrates an opaque, integrity-protected cursor. In production, keep the cursor key in a managed secret or KMS-backed key-management path, version keys for rotation, and bind claims to the authenticated caller and query.

import { createHmac, timingSafeEqual } from "node:crypto";

const key = Buffer.from(process.env.CURSOR_KEY!, "base64");

type Claims = {
  tenantId: string;
  principalId: string;
  queryHash: string;
  upstreamToken: string;
  expiresAt: number;
};

function encodeCursor(claims: Claims): string {
  const body = Buffer.from(JSON.stringify(claims)).toString("base64url");
  const mac = createHmac("sha256", key).update(body).digest("base64url");
  return `${body}.${mac}`;
}

function decodeCursor(cursor: string, tenantId: string, principalId: string): Claims {
  const [body, suppliedMac] = cursor.split(".");
  if (!body || !suppliedMac) throw new Error("Invalid cursor");

  const expectedMac = createHmac("sha256", key).update(body).digest();
  const actualMac = Buffer.from(suppliedMac, "base64url");
  if (actualMac.length !== expectedMac.length ||
      !timingSafeEqual(actualMac, expectedMac)) {
    throw new Error("Invalid cursor");
  }

  const claims = JSON.parse(Buffer.from(body, "base64url").toString()) as Claims;
  if (claims.expiresAt <= Date.now() ||
      claims.tenantId !== tenantId ||
      claims.principalId !== principalId) {
    throw new Error("Expired or unauthorized cursor");
  }
  return claims;
}

const cursor = encodeCursor({
  tenantId: "tenant-1",
  principalId: "user-7",
  queryHash: "sha256-of-normalized-query",
  upstreamToken: "vendor-next-page-token",
  expiresAt: Date.now() + 15 * 60_000
});
console.log(decodeCursor(cursor, "tenant-1", "user-7").upstreamToken);

Notice that a signed cursor is tamper-evident, not confidential; encrypt it too if the upstream token is sensitive.

The realistic tool example uses the TypeScript MCP SDK, a Zod input schema, and application services injected into the handler. callerContext represents identity established by trusted request middleware; it must never be populated from tool arguments. The result is deliberately bounded, and the continuation cursor is tied to the normalized query and caller.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

type Caller = { tenantId: string; principalId: string; scopes: string[] };
type Services = {
  requireScope(caller: Caller, scope: string): void;
  reserveQuota(caller: Caller, tool: string): Promise<void>;
  connectionFor(caller: Caller): Promise<{
    accessToken: string;
    apiBaseUrl: string;
  }>;
  decodeCursor(cursor: string, caller: Caller, queryHash: string): string;
  encodeCursor(token: string, caller: Caller, queryHash: string): string;
};

export function registerTools(server: McpServer, services: Services) {
  server.tool(
    "search_customers",
    "Search CRM customers. Returns at most 50 records and an optional continuation cursor.",
    {
      query: z.string().trim().min(1).max(200),
      pageSize: z.number().int().min(1).max(50).default(25),
      cursor: z.string().max(2048).optional()
    },
    async ({ query, pageSize, cursor }, extra) => {
      const caller = callerContext(extra) as Caller;
      services.requireScope(caller, "crm:customers:read");
      await services.reserveQuota(caller, "search_customers");

      const normalizedQuery = query.toLocaleLowerCase();
      const queryHash = hashQuery(normalizedQuery, pageSize);
      const pageToken = cursor
        ? services.decodeCursor(cursor, caller, queryHash)
        : undefined;
      const connection = await services.connectionFor(caller);

      const response = await fetch(
        `${connection.apiBaseUrl}/v1/customers/search`,
        {
          method: "POST",
          headers: {
            authorization: `Bearer ${connection.accessToken}`,
            "content-type": "application/json"
          },
          body: JSON.stringify({ query: normalizedQuery, limit: pageSize, pageToken }),
          signal: AbortSignal.timeout(5_000)
        }
      );

      if (response.status === 429) {
        throw new Error("CRM rate limit reached; retry after the indicated interval");
      }
      if (!response.ok) throw new Error(`CRM request failed: ${response.status}`);

      const body = await response.json() as {
        items: Array<{ id: string; name: string; email?: string }>;
        nextPageToken?: string;
      };

      const nextCursor = body.nextPageToken
        ? services.encodeCursor(body.nextPageToken, caller, queryHash)
        : undefined;

      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            customers: body.items.map(({ id, name, email }) => ({ id, name, email })),
            nextCursor
          })
        }]
      };
    }
  );
}

Notice that the SaaS token is used only in the outbound request, while the tool result contains a deliberately selected projection rather than the raw response.

The exact transport wiring and authentication integration depend on the MCP SDK release and the chosen authorization server. Keep transport construction in a separate composition module. The service must validate the bearer token before creating an authenticated caller context; a tool handler must not trust a tenant ID, user ID, role, or scope supplied by the model.

7. Key flows

The first sequence shows a caller invoking a tool. Authentication and authorization happen before the SaaS call; quota enforcement applies to the caller and tenant, not merely to a process-local counter.

sequenceDiagram
    participant C as "MCP client"
    participant M as "MCP service on Fargate"
    participant I as "Authorization server"
    participant R as "ElastiCache Redis"
    participant D as "Aurora PostgreSQL"
    participant S as "SaaS API"
    C->>M: "Tool call with MCP access token"
    M->>I: "Validate issuer keys and token claims"
    I-->>M: "Valid identity, audience, scopes"
    M->>M: "Authorize tool and resolve tenant"
    M->>R: "Reserve tenant and user quota"
    R-->>M: "Allowed or retry interval"
    M->>D: "Load caller SaaS connection"
    D-->>M: "Encrypted delegated token"
    M->>M: "Decrypt token and validate cursor"
    M->>S: "Call bounded SaaS query"
    S-->>M: "Page of results and next token"
    M->>M: "Project results and issue cursor"
    M-->>C: "Tool result"

The service does not forward MCP credentials to the SaaS API or SaaS credentials back to the MCP client.

The second sequence shows the connection flow. Use state and nonce checks in the OAuth callback, validate the callback against the initiating principal, and persist tokens only after successful code exchange. Refresh-token rotation must update the stored token bundle atomically so concurrent refreshes do not overwrite a newer token.

sequenceDiagram
    participant C as "MCP client"
    participant M as "MCP service"
    participant U as "User browser"
    participant A as "SaaS authorization server"
    participant D as "Aurora PostgreSQL"
    participant K as "AWS KMS"
    C->>M: "Start connect tool or link flow"
    M->>M: "Create one-time state bound to principal"
    M-->>C: "Authorization URL"
    C->>U: "Open authorization URL"
    U->>A: "Authorize delegated access"
    A-->>M: "Callback with code and state"
    M->>M: "Validate state and principal binding"
    M->>A: "Exchange code for SaaS tokens"
    A-->>M: "Access and refresh tokens"
    M->>K: "Encrypt token bundle"
    K-->>M: "Ciphertext and key metadata"
    M->>D: "Persist connection transactionally"
    D-->>M: "Connection saved"
    M-->>C: "Connection ready"

The user’s authorization to the SaaS API is a separate consent flow from authorization to invoke MCP tools.

8. Build and release

Infrastructure should be versioned alongside application code. This excerpt illustrates the ECS service boundary; production Terraform also needs VPC subnets, security groups, ALB target groups and listeners, IAM task and execution roles, Aurora, Redis, SQS, KMS, Secrets Manager, log groups, alarms, and backups.

resource "aws_ecs_cluster" "mcp" {
  name = "saas-mcp"
}

resource "aws_ecs_task_definition" "mcp" {
  family                   = "saas-mcp"
  requires_compatibilities = ["FARGATE"]
  network_mode             = "awsvpc"
  cpu                      = 1024
  memory                   = 2048
  execution_role_arn       = aws_iam_role.execution.arn
  task_role_arn            = aws_iam_role.application.arn

  container_definitions = jsonencode([{
    name      = "mcp"
    image     = "${aws_ecr_repository.mcp.repository_url}:${var.image_tag}"
    essential = true
    portMappings = [{ containerPort = 3000, protocol = "tcp" }]
    environment = [
      { name = "NODE_ENV", value = "production" },
      { name = "PORT", value = "3000" }
    ]
    secrets = [{
      name      = "DATABASE_URL"
      valueFrom = aws_secretsmanager_secret.database.arn
    }]
    logConfiguration = {
      logDriver = "awslogs"
      options = {
        awslogs-group         = aws_cloudwatch_log_group.mcp.name
        awslogs-region        = var.aws_region
        awslogs-stream-prefix = "mcp"
      }
    }
  }])
}

resource "aws_ecs_service" "mcp" {
  name            = "saas-mcp"
  cluster         = aws_ecs_cluster.mcp.id
  task_definition = aws_ecs_task_definition.mcp.arn
  desired_count   = 2
  launch_type     = "FARGATE"

  deployment_circuit_breaker {
    enable   = true
    rollback = true
  }

  network_configuration {
    subnets          = var.private_subnet_ids
    security_groups  = [aws_security_group.mcp.id]
    assign_public_ip = false
  }

  load_balancer {
    target_group_arn = aws_lb_target_group.mcp.arn
    container_name   = "mcp"
    container_port   = 3000
  }
}

Notice that the tasks have no public IP and use a dedicated task role; the omitted network and IAM resources are mandatory production configuration, not optional hardening.

A staged GitHub Actions pipeline should run tests on pull requests, publish an immutable image, deploy to staging, run smoke and contract checks, then promote the same image to production after approval. The example assumes repository OIDC federation to AWS rather than long-lived AWS keys.

name: mcp-service
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run test:contract
      - run: npm run build

  release:
    if: github.event_name == 'push'
    needs: verify
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
          aws-region: us-east-1
      - run: ./scripts/build-and-push-image.sh "${GITHUB_SHA}"
      - run: ./scripts/deploy.sh staging "${GITHUB_SHA}"
      - run: npm run test:smoke -- --target=staging
      - run: ./scripts/deploy.sh production "${GITHUB_SHA}"

Notice that production receives the tested image digest; a rebuild between staging and production would weaken the release guarantee.

Test at four levels:

  • Unit: cursor binding, token expiry, scope policies, error translation, quota math, and result projection.
  • Integration: PostgreSQL constraints and transactions, Redis atomic quota scripts, KMS encryption/decryption, and SQS outbox delivery.
  • Contract: MCP tool schemas and responses, plus SaaS API pagination, authentication, and error behavior against a sandbox or controlled stub.
  • Load: representative concurrency, slow upstream calls, tenant skew, token refresh contention, large pages, and 429 responses. Verify graceful rejection and bounded resource use, not only peak throughput.

9. Observability

Instrument the request as a trace across transport, policy, cache, database, token refresh, and upstream HTTP calls. Use low-cardinality dimensions: tool name, status class, and dependency. Do not use tenant IDs, principal IDs, customer names, URLs containing query data, or cursor values as metric labels.

A structured log event should be useful without exposing secrets:

{
  "timestamp": "2026-11-11T12:00:00.000Z",
  "level": "warn",
  "event": "saas_request_throttled",
  "request_id": "req-8f2a",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "tool": "search_customers",
  "tenant_ref": "hmac:7f1c",
  "upstream_status": 429,
  "retry_after_ms": 1200
}

Use a keyed pseudonymous tenant reference only where operational correlation is approved; rotate or protect its HMAC key. Never log authorization headers, token material, raw tool arguments, full upstream response bodies, or authorization codes.

For a TypeScript service using OpenTelemetry, initialize the Node SDK before importing instrumented application modules. Export traces through OTLP to the selected collector or observability backend.

import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { trace, SpanStatusCode } from "@opentelemetry/api";

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
  }),
  instrumentations: [getNodeAutoInstrumentations()]
});

await sdk.start();

const tracer = trace.getTracer("saas-mcp");

export async function callSaaS<T>(operation: () => Promise<T>): Promise<T> {
  return tracer.startActiveSpan("saas.request", async (span) => {
    try {
      return await operation();
    } catch (error) {
      span.recordException(error as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw error;
    } finally {
      span.end();
    }
  });
}

Notice that the span records operation outcome, not user data; add only bounded attributes such as dependency name and response status.

Track RED for the service and USE for constrained resources:

SignalMetrics
RED — RateMCP requests/s by tool and outcome; upstream requests/s by dependency
RED — ErrorsHTTP and tool error rates; auth failures; SaaS 429/5xx rates; refresh failures
RED — DurationMCP request latency and upstream latency histograms; token refresh duration
USE — UtilizationECS CPU and memory; Aurora connections and storage; Redis memory; SQS queue age
USE — SaturationTask CPU throttling, database connection-pool wait, Redis evictions, queue depth, pending requests

Proposed SLIs and SLOs are starting targets to validate with product owners:

SLIProposed SLOMeasurement boundary
Successful MCP tool requests99.9% monthly, excluding caller errors and upstream SaaS availability failuresRequests accepted by the service and completed without an internal error
MCP adapter latency95% under 500 ms excluding SaaS response timeService-side processing, measured separately from upstream duration
Authentication availability99.95% monthly for local token validation and key retrievalValid-token requests that pass authentication
Cursor continuity99.9% of valid, unexpired cursors resume successfullyExcludes vendor invalidation or expired cursors

Dashboards should show request volume and errors by tool, latency split between adapter and SaaS, tenant throttling counts, token refresh outcomes, task health, database pool saturation, Redis health, and queue age. Page on sustained SLO burn, no healthy tasks, database unavailability or connection exhaustion, repeated key or token-validation failure, and a growing queue that risks missing operational processing objectives. Notify rather than page for isolated SaaS 429s; page only when the service is broadly failing its own SLO or a vendor outage requires action.

10. Security and compliance

Treat the MCP endpoint as a multi-tenant API. The model may choose tool arguments, but the server derives identity from validated credentials and derives tenant membership from trusted records.

  • Validate token signature, issuer, audience, expiry, and required scopes. Rotate and cache JWKS safely; fail closed when a key cannot be validated.
  • Use distinct OAuth clients, audiences, scopes, and token lifetimes for MCP access and SaaS delegation. Do not forward one token to both services.
  • Bind the OAuth callback state to the initiating principal, use one-time state, validate redirect URIs, and protect against CSRF and authorization-code replay.
  • Encrypt SaaS token bundles with envelope encryption and restrict KMS decrypt permissions to the runtime task role. Make token refresh updates atomic and handle refresh-token rotation.
  • Enforce tenant ownership in application queries and database constraints. Add integration tests that attempt cross-tenant access for every connection and cursor path.
  • Use TLS in transit, private subnets for tasks and data services, least-privilege security groups, and egress controls appropriate to the SaaS API’s network model.
  • Define tool allowlists and safe output projections. Apply request-size, page-size, timeout, and response-size limits.
  • Redact secrets and personal data from logs, traces, errors, and support tooling. Set explicit data retention and deletion behavior for connection metadata and audit records.
  • Maintain a threat model covering confused-deputy behavior, prompt injection through returned CRM data, replayed cursors, stolen refresh tokens, and malicious or compromised MCP clients.

Compliance depends on the customer base, data processed, and contractual obligations. A cloud service being available in a compliant environment does not make this application compliant by itself. Record data flows, retention, access reviews, incident procedures, and vendor responsibilities for the actual scope.

11. Cost

This is an assumption-based monthly estimate, not a quote. It assumes one AWS region, modest multi-AZ production capacity, staging at reduced size, the workload in the context table, and no unusually high data transfer or log ingestion. Prices vary by region, usage, commitment, and service configuration; validate with the AWS Pricing Calculator before approval.

Cost areaMonthly planning estimateAssumption
ECS Fargate tasks$650Small production service and worker pool across AZs, plus reduced staging capacity
Application Load Balancer and WAF$250One public ingress path with moderate request and rule usage
Aurora PostgreSQL$900Multi-AZ production database, backups, storage, and a smaller staging database
ElastiCache for Redis$400Production cache with redundancy plus a small staging allocation
SQS, KMS, Secrets Manager$100Moderate queue traffic and key/secret usage
CloudWatch and tracing$450Application logs, metrics, alarms, and sampled traces with retention controls
ECR, network transfer, miscellaneous$350Container storage, expected data transfer, and supporting resources
Total$3,100Planning estimate; excludes tax, SaaS charges, and shared platform costs

The most controllable cost lever is often telemetry volume, followed by always-on nonproduction capacity. Do not reduce production redundancy or audit coverage to meet an arbitrary target without explicitly accepting the resulting risk. Monitor actual cost by environment and service, and alert on budget variance.

12. Failure modes, resilience and disaster recovery

Failure modeExpected behaviorRecovery or control
SaaS API returns 429Stop retrying aggressively; return a useful retry interval and preserve the user’s ability to retryHonor Retry-After, share quota state by tenant where vendor limits are tenant-wide
SaaS API times out or returns 5xxBound the request by a deadline; retry only safe reads, at most a small number of timesCircuit breaker and per-dependency concurrency limit
SaaS token expiresRefresh once under coordination; retry the original safe read only if appropriateAtomic token update; send user through consent again if refresh is revoked
Redis unavailableReject or conservatively limit sensitive high-volume operations rather than silently removing all quotasHealth checks, bounded local fallback only if explicitly designed, restore Redis service
Aurora unavailableFail requests that require connection or audit state; do not fall back to an untrusted token cacheMulti-AZ failover, connection retry with jitter, tested backups
Queue backlog growsPrioritize token-refresh and audit-processing policies; alert before expiry or retention objectives are missedScale workers within bounds, inspect poison messages and downstream causes
Cursor tampered, expired, or mismatchedReject it; do not interpret it as a new unbounded querySigned/encrypted cursor, caller and query binding, short expiry
Deployment regressionStop or roll back the releaseECS deployment circuit breaker, staging smoke tests, immutable image promotion

Multi-AZ availability addresses a zone failure, not a regional disaster. A reasonable initial DR assumption is a regional recovery point objective of 15 minutes and a recovery time objective of four hours; these are proposed targets to approve and test, not guaranteed service behavior. Use automated database backups and point-in-time recovery, keep infrastructure definitions reproducible, and document how to restore KMS access, secrets, database data, and task configuration in a recovery region. If the SaaS provider or identity provider is unavailable, regional recovery does not restore their availability; the service should report that dependency failure clearly.

13. Evolving to the next scale

Do not split services because the diagram looks more sophisticated. Split when ownership, isolation, or scaling measurements justify the operational cost.

TriggerChange
Tool modules change at different rates but share a team and data modelKeep the modular monolith; strengthen module boundaries and contract tests
A tool family has independent scaling or release needsExtract that tool family behind an internal API; preserve one public MCP contract
Redis quota state is too hot for shared keys or noisy tenantsPartition quota keys by tenant, use atomic scripts carefully, and introduce explicit tenant fairness policies
Database connection pressure grows with task countAdd a managed connection proxy, tune pools, and separate read-heavy audit queries from connection metadata
Audit retention or query needs grow substantiallyExport the outbox stream to a dedicated analytics store; keep operational metadata in PostgreSQL
Geographic latency or residency becomes a requirementDefine regional ownership for tenants, token residency, and failover semantics before deploying regional copies
SaaS calls dominate latency or consume quotaAdd narrowly scoped caching only for data with explicit freshness and authorization rules; do not cache user-specific results by URL alone

For every scale change, re-check the security boundary. A cache key, queue message, replica, or regional copy can become a cross-tenant leak if the tenant and principal context are not carried and verified consistently.

14. Phased implementation plan

  1. Confirm contracts and threat model. Document the MCP protocol transport, authorization-server capabilities, SaaS OAuth scopes, vendor rate-limit semantics, pagination behavior, data classification, and expected tool set.
  2. Build the vertical slice. Implement one read-only tool, token validation, one delegated SaaS connection, bounded response projection, timeout handling, and a staging deployment.
  3. Add state and guardrails. Introduce PostgreSQL migrations, KMS-backed token encryption, cursor binding, Redis quotas, request limits, and cross-tenant authorization tests.
  4. Productionize operations. Add queue-backed refresh and audit delivery, OpenTelemetry, dashboards, SLO reporting, alarms, backup and restore drills, and runbooks for vendor throttling and credential revocation.
  5. Release progressively. Run contract and load tests against representative conditions, onboard a small pilot, inspect authorization and throttle outcomes, then increase access in controlled stages.
  6. Review after real traffic. Compare measured latency, tenant skew, cache behavior, error rates, and cloud cost with the assumptions. Change the design only where evidence shows a constraint.

The central design rule is simple: the MCP server is a policy-enforcing adapter, not a credential relay. Keep caller identity, delegated SaaS identity, pagination state, and rate-limit accounting separate. That separation is what makes the integration predictable under both ordinary traffic and failure.


This article was generated with AI. #AIGenerated