# 1 · register once
POST https://mcp.optimove.net/register
Content-Type: application/json

{"client_name": "Your Platform",
 "redirect_uris": ["https://ai.yourcompany.example/oauth/optimove/callback"],
 "grant_types": ["authorization_code", "refresh_token"],
 "response_types": ["code"],
 "token_endpoint_auth_method": "none"}

→ 201  {"client_id": "gAAAAAB…", "client_id_issued_at": 1793…, "redirect_uris": [...], ...}

# 2 · open in the user's browser
https://mcp.optimove.net/authorize?response_type=code
  &client_id=gAAAAAB…
  &redirect_uri=https%3A%2F%2Fai.yourcompany.example%2Foauth%2Foptimove%2Fcallback
  &code_challenge=<base64url(sha256(verifier))>&code_challenge_method=S256
  &state=<random>&resource=https%3A%2F%2Fmcp.optimove.net%2Fmcp

# 3 · the browser lands on your callback
GET https://ai.yourcompany.example/oauth/optimove/callback?code=gAAAAAB…&state=<random>

# 4 · redeem
POST https://mcp.optimove.net/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=gAAAAAB…&code_verifier=<verifier>
  &redirect_uri=https%3A%2F%2Fai.yourcompany.example%2Foauth%2Foptimove%2Fcallback&client_id=gAAAAAB…

→ 200  {"access_token": "gAAAAAB…", "refresh_token": "gAAAAAB…", "token_type": "Bearer", "expires_in": 90}

# 5 · call
POST https://mcp.optimove.net/mcp
Authorization: Bearer gAAAAAB…
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-06-18
Content-Type: application/json

{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}

// Node 18+, built-in fetch and crypto. Same steps as the HTTP walkthrough.
// CLIENT_ID is the one returned by step 1 (register).
import { randomBytes, createHash } from "node:crypto";

const BASE = "https://mcp.optimove.net";
const CALLBACK = "https://ai.yourcompany.example/oauth/optimove/callback";
const CLIENT_ID = "<your client_id>";

// Step 2: start sign-in. Open the returned URL in the person's browser.
export function startSignIn(session) {
  session.verifier = randomBytes(32).toString("base64url");
  session.state = randomBytes(16).toString("base64url");
  const url = new URL(`${BASE}/authorize`);
  url.search = new URLSearchParams({
    response_type: "code", client_id: CLIENT_ID, redirect_uri: CALLBACK,
    code_challenge: createHash("sha256").update(session.verifier).digest("base64url"),
    code_challenge_method: "S256", state: session.state, resource: `${BASE}/mcp`,
  });
  return url.toString();
}

// Steps 3-4: your callback receives ?code=…&state=… (or ?error=…)
export async function finishSignIn(session, query) {
  if (query.state !== session.state) throw new Error("state mismatch");
  if (query.error) throw new Error(`${query.error}: ${query.error_description}`);
  session.tokens = await token({
    grant_type: "authorization_code", code: query.code,
    code_verifier: session.verifier, redirect_uri: CALLBACK, client_id: CLIENT_ID,
  });
}

async function token(form) {
  const res = await fetch(`${BASE}/token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams(form),
  });
  // A 503 is not a sign-out: wait Retry-After seconds and retry with the same refresh token.
  if (!res.ok) throw Object.assign(new Error(`token ${res.status}`), { status: res.status, retryAfter: res.headers.get("Retry-After") });
  const t = await res.json();
  return { ...t, expiresAt: Date.now() + t.expires_in * 1000 };
}

// Access tokens live 90 seconds. Refresh shortly before, one refresh at a time per session.
export async function accessToken(session) {
  if (Date.now() < session.tokens.expiresAt - 10_000) return session.tokens.access_token;
  session.refreshing ??= token({
    grant_type: "refresh_token", refresh_token: session.tokens.refresh_token, client_id: CLIENT_ID,
  }).finally(() => { session.refreshing = undefined; });
  session.tokens = await session.refreshing;
  return session.tokens.access_token;
}

// Step 5: call the MCP endpoint (JSON-RPC 2.0 over Streamable HTTP)
let nextId = 1;
export async function mcp(session, method, params = {}) {
  const res = await fetch(`${BASE}/mcp`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${await accessToken(session)}`,
      "Content-Type": "application/json",
      Accept: "application/json, text/event-stream",
      "MCP-Protocol-Version": "2025-06-18",
    },
    body: JSON.stringify({ jsonrpc: "2.0", id: String(nextId++), method, params }),
  });
  if (!res.ok) throw new Error(`mcp ${res.status}: ${await res.text()}`);
  const text = await res.text();
  // A streamed reply carries the JSON-RPC message on its last "data:" line.
  const json = res.headers.get("content-type")?.includes("text/event-stream")
    ? text.split("\n").filter((l) => l.startsWith("data:")).pop().slice(5)
    : text;
  return JSON.parse(json);
}

// await mcp(session, "initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "your-platform", version: "1" } });
// await mcp(session, "tools/call", { name: "explorer", arguments: { focus: "tenant" } });

# pip install mcp
from mcp.client.auth import OAuthClientProvider, TokenStorage
from mcp.client.streamable_http import streamablehttp_client
from mcp.client.session import ClientSession
from mcp.shared.auth import OAuthClientMetadata

metadata = OAuthClientMetadata(
    client_name="Your Platform",
    redirect_uris=["https://ai.yourcompany.example/oauth/optimove/callback"],
    grant_types=["authorization_code", "refresh_token"],
    response_types=["code"],
    token_endpoint_auth_method="none",
)

auth = OAuthClientProvider(
    server_url="https://mcp.optimove.net/mcp",
    client_metadata=metadata,
    storage=YourTokenStorage(session_id),       # implements TokenStorage: get/set tokens and client info
    redirect_handler=open_in_users_browser,     # async (url) -> None
    callback_handler=wait_for_your_callback,    # async () -> (code, state)
)

async with streamablehttp_client("https://mcp.optimove.net/mcp", auth=auth) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        result = await session.call_tool("explorer", {"focus": "tenant"})

// npm install @modelcontextprotocol/client
import {
  Client, StreamableHTTPClientTransport, UnauthorizedError,
  type OAuthClientProvider, type OAuthClientMetadata, type OAuthClientInformationMixed,
  type OAuthClientInformationContext, type OAuthTokens, type OAuthDiscoveryState,
} from "@modelcontextprotocol/client";

const MCP_URL = new URL("https://mcp.optimove.net/mcp");
const CALLBACK = "https://ai.yourcompany.example/oauth/optimove/callback";

// One provider per signed-in person. Persist what it stores so a restart doesn't mean a new sign-in.
class OptimoveAuth implements OAuthClientProvider {
  private clients = new Map<string, OAuthClientInformationMixed>();
  private saved?: OAuthTokens;
  private verifier?: string;
  private discovery?: OAuthDiscoveryState;
  lastState?: string;

  readonly redirectUrl = CALLBACK;
  readonly clientMetadata: OAuthClientMetadata = {
    client_name: "Your Platform",
    redirect_uris: [CALLBACK],
    grant_types: ["authorization_code", "refresh_token"],
    response_types: ["code"],
    token_endpoint_auth_method: "none",
  };

  clientInformation(ctx?: OAuthClientInformationContext) { return ctx ? this.clients.get(ctx.issuer) : undefined; }
  saveClientInformation(info: OAuthClientInformationMixed, ctx?: OAuthClientInformationContext) { if (ctx) this.clients.set(ctx.issuer, info); }
  tokens() { return this.saved; }
  saveTokens(tokens: OAuthTokens) { this.saved = tokens; }
  state() { this.lastState = crypto.randomUUID(); return this.lastState; }
  saveDiscoveryState(s: OAuthDiscoveryState) { this.discovery = s; }
  discoveryState() { return this.discovery; }
  redirectToAuthorization(url: URL) { openInUsersBrowser(url); }
  saveCodeVerifier(v: string) { this.verifier = v; }
  codeVerifier() { if (!this.verifier) throw new Error("no code verifier"); return this.verifier; }
}

const auth = new OptimoveAuth();
const client = new Client({ name: "your-platform", version: "1.0.0" });
const transport = new StreamableHTTPClientTransport(MCP_URL, { authProvider: auth });

try {
  await client.connect(transport); // first time: registers, sends the person to sign in, throws
} catch (e) {
  if (!(e instanceof UnauthorizedError)) throw e;
  const params = new URL(await waitForYourCallback()).searchParams;
  if (params.get("state") !== auth.lastState) throw new Error("state mismatch");
  await transport.finishAuth(params); // redeems the code and saves the tokens
  await client.connect(new StreamableHTTPClientTransport(MCP_URL, { authProvider: auth }));
}

const { tools } = await client.listTools();
const result = await client.callTool({ name: "explorer", arguments: { focus: "tenant" } });
// A refused call is ordinary content: its JSON text carries `error` and `failure_domain` (isError is not set).

// npm install @anthropic-ai/sdk
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();

const response = await anthropic.beta.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 16000,
  betas: ["mcp-client-2025-11-20", "server-side-fallback-2026-07-01"],
  fallbacks: "default",
  mcp_servers: [{
    type: "url",
    url: "https://mcp.optimove.net/mcp",
    name: "optimove",
    authorization_token: await accessToken(session),
  }],
  tools: [{ type: "mcp_toolset", mcp_server_name: "optimove" }],
  messages: [{ role: "user", content: "Which Optimove account am I connected to?" }],
});
for (const block of response.content) if (block.type === "text") console.log(block.text);

# pip install anthropic
import anthropic
client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["mcp-client-2025-11-20", "server-side-fallback-2026-07-01"],
    fallbacks="default",
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.optimove.net/mcp",
        "name": "optimove",
        "authorization_token": access_token,  # refreshed just before this call
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "optimove"}],
    messages=[{"role": "user", "content": "Which Optimove account am I connected to?"}],
)

// npm install @anthropic-ai/claude-agent-sdk
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List my draft campaigns in Optimove",
  options: {
    mcpServers: {
      optimove: {
        type: "http",
        url: "https://mcp.optimove.net/mcp",
        headers: { Authorization: `Bearer ${await accessToken(session)}` },
      },
    },
    allowedTools: ["mcp__optimove__*"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") console.log(message.result);
}

# Refresh: every ~80 seconds, or on the first 401 from /mcp
POST https://mcp.optimove.net/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<current>&client_id=<yours>

# Sign out: revoking either token ends the whole session within 90 seconds
POST https://mcp.optimove.net/revoke
Content-Type: application/x-www-form-urlencoded

token=<access or refresh token>&client_id=<yours>

{"jsonrpc":"2.0","id":"1","method":"initialize",
 "params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"your-platform","version":"1"}}}

{"jsonrpc":"2.0","id":"2","method":"tools/list","params":{}}

{"jsonrpc":"2.0","id":"3","method":"tools/call",
 "params":{"name":"explorer","arguments":{"focus":"tenant"}}}