AdminConsole
Tutorials/Advanced
Advanced55 minMCP

Provision and validate a remote MCP client

Approve exact authority, deliver a signed pre-registration event, inspect discovery, validate PKCE and resource binding, then revoke without transporting a token or secret.

By the endA replay-safe client identity journey with durable registration, request checks, revocation, and audit evidence.
Real-world scenario

Build against an explicit contract

A platform team must provision a remote MCP client against an external authorization server, prove OAuth discovery and request binding, and revoke it without turning control-plane events into a credential channel.

A Mappls developer projectA restricted MCP applicationFixture data with no production credentialsA request, aggregate, or correlation ID strategy
Step 1

Define the user and system contract

A platform team must provision a remote MCP client against an external authorization server, prove OAuth discovery and request binding, and revoke it without turning control-plane events into a credential channel. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Freeze the registration contract

Bind one developer application to the exact client kind, callback, issuer, MCP resource audience, least scope, tool allowlist, purpose, and reviewer decision before provisioning begins.

AI & Location · SDK or product slice
const nearbyPlacesTool = {
  name: "mappls_search_nearby",
  description: "Find real places near a validated Mappls Pin or coordinate.",
  inputSchema: {
    type: "object",
    required: ["location", "category"],
    properties: {
      location: { type: "string", description: "Mappls Pin or 'lat,lng'." },
      category: { type: "string" },
      radiusMeters: { type: "integer", minimum: 50, maximum: 10_000 }
    }
  }
};
Step 3

Deliver one authenticated effect

Lease the durable outbox event, sign timestamp, event ID, and exact body with a managed HMAC key, reject stale or oversized deliveries, and deduplicate by event ID plus body hash.

Use the normalized source contract below as the executable boundary. Switch tabs to compare credential-safe languages without changing the operation.

GET /models
curl --request GET \
  --url 'https://ai.mappls.com/models' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Inspect parameters, responses, and source fingerprint
Step 4

Persist the external identity

Provision through the authorization server management seam, store only the non-secret external client ID and receipt, return the strict result contract, and reconcile a timeout before retrying any new effect.

Step 5

Prove discovery and request binding

Publish RFC 9728 protected-resource metadata, discover RFC 8414 issuer metadata, require authorization code plus PKCE S256, and include the exact RFC 8707 resource in authorization and token requests.

Step 6

Revoke without erasing evidence

Deliver a signed revocation for the same registration aggregate and external identity, disable it at the issuer, preserve receipts and audit, and verify that subsequent authorization checks fail closed.

Step 7

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when an exact retry returns the original registration result; event-id reuse with different bytes conflicts; redirect, issuer, resource, pkce, state, and least scope are validated; no code, token, client secret, or provider credential crosses the adapter callback; restart and revocation preserve attributable evidence. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

signature is wrong, stale, replayed with changed bytes, or too large

Fail fast with a typed, user-safe outcome and preserve the original request identity.

authorization-server mutation succeeds but the response is lost

Keep the last verified state, mark freshness honestly, and retry only within the documented idempotency boundary.

callback, resource audience, PKCE method, or requested scope drifts

Reconcile durable local and provider evidence before declaring success or issuing a compensating command.

revocation targets an unknown or already retired external identity

Reconcile durable local and provider evidence before declaring success or issuing a compensating command.

Never turn uncertainty into success

Timeout after a stateful command is an unknown outcome. Query by provider/idempotency identity or wait for authoritative events; do not blindly retry a new command.

Acceptance criteria

Definition of done

an exact retry returns the original registration resultevent-ID reuse with different bytes conflictsredirect, issuer, resource, PKCE, state, and least scope are validatedno code, token, client secret, or provider credential crosses the adapter callbackrestart and revocation preserve attributable evidence

MCP production checks

Tools expose the least authority neededState-changing calls require explicit policy and approvalResponses identify source, freshness, and uncertaintyEvery tool call is tenant-scoped, metered, redacted, and traceable
Grounded implementation

Continue from source, contracts, and a full app

These links resolve to repository-derived evidence; unsupported package names and endpoints are not filled in from guesswork.

Study the complete Governed spatial agent run state machine
Tutorial complete

Run it, break it, then observe it

Start with fixture credentials, execute the failure plan, and use request logs, usage, webhook evidence, and operational metrics before promoting traffic.