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.
| Dimension | Assumption |
|---|---|
| Users | 30,000 daily users across 1,000 customer tenants |
| Requests | 20 requests/s average; 120 requests/s short peak across MCP calls |
| Data volume | 10 GB relational data, primarily connection metadata and audit records; SaaS business data remains upstream |
| Team size | 5 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:
| ID | Requirement | Acceptance condition |
|---|---|---|
| F1 | Discover and invoke MCP tools over Streamable HTTP | MCP clients can list tools and call supported tools |
| F2 | Authenticate MCP callers | Every protected request has a valid issuer, audience, expiry, and required scope |
| F3 | Connect a user to the SaaS API | Delegated SaaS credentials are stored and refreshed without exposing them to the model |
| F4 | Read SaaS data with pagination | Results are bounded, and a continuation cursor can resume the same query |
| F5 | Enforce quotas | Per-tenant and per-user limits apply before upstream calls |
| F6 | Audit access | Tool name, tenant, principal, outcome, and request ID are recorded without secrets or sensitive payloads |
Non-functional requirements:
| Area | Requirement | Design response |
|---|---|---|
| Availability | Proposed 99.9% monthly availability for MCP tool requests, excluding upstream SaaS outages | Multi-AZ tasks and database; upstream failures are surfaced as bounded tool errors |
| Latency | Keep adapter overhead low enough that the upstream API is the usual latency contributor | Avoid unnecessary persistence on the request path; use connection pooling and bounded responses |
| Security | Tenant isolation and least-privilege delegated access | Token validation, tenant-scoped queries, encrypted token storage, tool-level authorization |
| Resilience | No retry storm against a failing or throttled SaaS API | Rate-limit reservations, bounded retries for safe reads, circuit breaker, Retry-After handling |
| Operability | Diagnose failures across MCP, database, cache, queue, and SaaS calls | Correlated logs, traces, service and resource metrics, actionable alerts |
| Maintainability | Add tools without coupling protocol handling to SaaS details | Separate 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.
| Component | AWS choice | Azure equivalent | GCP equivalent |
|---|---|---|---|
| Edge filtering and ingress | AWS WAF + Application Load Balancer | Azure WAF + Application Gateway | Cloud Armor + external Application Load Balancer |
| Container runtime | Amazon ECS on AWS Fargate | Azure Container Apps | Cloud Run |
| Relational metadata store | Amazon Aurora PostgreSQL | Azure Database for PostgreSQL | Cloud SQL for PostgreSQL |
| Distributed cache | Amazon ElastiCache for Redis | Azure Managed Redis | Memorystore for Redis |
| Background queue | Amazon SQS | Azure Service Bus queues | Cloud Tasks or Pub/Sub, depending on delivery model |
| Encryption keys | AWS KMS | Azure Key Vault | Cloud KMS |
| Secret management | AWS Secrets Manager | Azure Key Vault | Secret Manager |
| Logs and metrics | Amazon CloudWatch | Azure Monitor | Cloud Monitoring |
| Distributed tracing | AWS X-Ray with OpenTelemetry | Application Insights with OpenTelemetry | Cloud Trace with OpenTelemetry |
| Container images | Amazon ECR | Azure Container Registry | Artifact Registry |
| Infrastructure identity | ECS task roles | Managed identities | Workload 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 --> CursorCodecInterfaces 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:
| Signal | Metrics |
|---|---|
| RED — Rate | MCP requests/s by tool and outcome; upstream requests/s by dependency |
| RED — Errors | HTTP and tool error rates; auth failures; SaaS 429/5xx rates; refresh failures |
| RED — Duration | MCP request latency and upstream latency histograms; token refresh duration |
| USE — Utilization | ECS CPU and memory; Aurora connections and storage; Redis memory; SQS queue age |
| USE — Saturation | Task CPU throttling, database connection-pool wait, Redis evictions, queue depth, pending requests |
Proposed SLIs and SLOs are starting targets to validate with product owners:
| SLI | Proposed SLO | Measurement boundary |
|---|---|---|
| Successful MCP tool requests | 99.9% monthly, excluding caller errors and upstream SaaS availability failures | Requests accepted by the service and completed without an internal error |
| MCP adapter latency | 95% under 500 ms excluding SaaS response time | Service-side processing, measured separately from upstream duration |
| Authentication availability | 99.95% monthly for local token validation and key retrieval | Valid-token requests that pass authentication |
| Cursor continuity | 99.9% of valid, unexpired cursors resume successfully | Excludes 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 area | Monthly planning estimate | Assumption |
|---|---|---|
| ECS Fargate tasks | $650 | Small production service and worker pool across AZs, plus reduced staging capacity |
| Application Load Balancer and WAF | $250 | One public ingress path with moderate request and rule usage |
| Aurora PostgreSQL | $900 | Multi-AZ production database, backups, storage, and a smaller staging database |
| ElastiCache for Redis | $400 | Production cache with redundancy plus a small staging allocation |
| SQS, KMS, Secrets Manager | $100 | Moderate queue traffic and key/secret usage |
| CloudWatch and tracing | $450 | Application logs, metrics, alarms, and sampled traces with retention controls |
| ECR, network transfer, miscellaneous | $350 | Container storage, expected data transfer, and supporting resources |
| Total | $3,100 | Planning 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 mode | Expected behavior | Recovery or control |
|---|---|---|
| SaaS API returns 429 | Stop retrying aggressively; return a useful retry interval and preserve the user’s ability to retry | Honor Retry-After, share quota state by tenant where vendor limits are tenant-wide |
| SaaS API times out or returns 5xx | Bound the request by a deadline; retry only safe reads, at most a small number of times | Circuit breaker and per-dependency concurrency limit |
| SaaS token expires | Refresh once under coordination; retry the original safe read only if appropriate | Atomic token update; send user through consent again if refresh is revoked |
| Redis unavailable | Reject or conservatively limit sensitive high-volume operations rather than silently removing all quotas | Health checks, bounded local fallback only if explicitly designed, restore Redis service |
| Aurora unavailable | Fail requests that require connection or audit state; do not fall back to an untrusted token cache | Multi-AZ failover, connection retry with jitter, tested backups |
| Queue backlog grows | Prioritize token-refresh and audit-processing policies; alert before expiry or retention objectives are missed | Scale workers within bounds, inspect poison messages and downstream causes |
| Cursor tampered, expired, or mismatched | Reject it; do not interpret it as a new unbounded query | Signed/encrypted cursor, caller and query binding, short expiry |
| Deployment regression | Stop or roll back the release | ECS 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.
| Trigger | Change |
|---|---|
| Tool modules change at different rates but share a team and data model | Keep the modular monolith; strengthen module boundaries and contract tests |
| A tool family has independent scaling or release needs | Extract that tool family behind an internal API; preserve one public MCP contract |
| Redis quota state is too hot for shared keys or noisy tenants | Partition quota keys by tenant, use atomic scripts carefully, and introduce explicit tenant fairness policies |
| Database connection pressure grows with task count | Add a managed connection proxy, tune pools, and separate read-heavy audit queries from connection metadata |
| Audit retention or query needs grow substantially | Export the outbox stream to a dedicated analytics store; keep operational metadata in PostgreSQL |
| Geographic latency or residency becomes a requirement | Define regional ownership for tenants, token residency, and failover semantics before deploying regional copies |
| SaaS calls dominate latency or consume quota | Add 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
- 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.
- Build the vertical slice. Implement one read-only tool, token validation, one delegated SaaS connection, bounded response projection, timeout handling, and a staging deployment.
- Add state and guardrails. Introduce PostgreSQL migrations, KMS-backed token encryption, cursor binding, Redis quotas, request limits, and cross-tenant authorization tests.
- 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.
- 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.
- 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