using-clerk-connector

name	using-clerk-connector
description	Implements Clerk Backend API requests with automatic Bearer Token auth using generated clients and MCP tools. Use when doing ANYTHING that touches a Clerk resource in any way, load this skill.

Major Platform Resource: Clerk Backend API

Common: Interacting with Resources

Security: Never connect directly to APIs. Never use credentials in code. Always use generated clients or MCP tools.

Three ways to interact with Clerk:

1. MCP tools (direct, no code needed): Tools follow the pattern mcp__resources__<resourcetype>_<toolname>. Use mcp__resources__list_resources to discover available resources and their IDs.
2. Generated TypeScript clients (for app code): Call mcp__resource-tools__add-resource-client with a resourceId to generate a typed client. Clients are created in /clients/ (Next.js) or /src/clients/ (Vite).
3. HTTP proxy (Next.js apps): Use createProxyFetch from @major-tech/resource-client/next to call the Clerk API directly with automatic auth injection. See using-http-proxy for setup and usage — preferred when you need to hit endpoints not covered by MCP tools or the typed client, or when using an official SDK that accepts a custom fetch.

CRITICAL: Do NOT guess client method names or signatures. The TypeScript clients in @major-tech/resource-client have strongly typed inputs and outputs. ALWAYS read the actual client source code in the generated /clients/ directory (or the package itself) to verify available methods and their exact signatures before writing any client code.

Framework note: Next.js = resource clients must be used in server-side code only (Server Components, Server Actions, API Routes). Vite = call directly from frontend.

Error handling: Always check result.ok before accessing result.result.

Invocation keys must be static strings — use descriptive literals like "list-clerk-users", never dynamic values.

---

MCP Tools

• mcp__resources__clerk_get — Make a GET request to any Clerk Backend API endpoint. Args: resourceId, path, query?
• mcp__resources__clerk_list_users — List users with optional filtering. Args: resourceId, emailAddress?, limit?, offset?
• mcp__resources__clerk_get_user — Get a single user by ID. Args: resourceId, userId
• mcp__resources__clerk_list_organizations — List organizations. Args: resourceId, limit?, offset?
• mcp__resources__clerk_invoke — Make any HTTP request to the Clerk API (including writes). Args: resourceId, method, path, query?, body?, timeoutMs?

TypeScript Client

import { clerkClient } from "./clients";

// invoke(method, path, invocationKey, options?)
const result = await clerkClient.invoke("GET", "/v1/users", "list-users", {
    query: { limit: "10", offset: "0" },
});
if (result.ok) {
    const response = result.result;
    // response: { kind: "api", status: number, body: { kind: "json"|"text"|"binary", value: ... } }
}

// POST example - create an invitation
await clerkClient.invoke("POST", "/v1/invitations", "create-invitation", {
    body: { type: "json", value: { email_address: "[e-mail]" } },
});

Example: Search for Users by Email

Using MCP tools (no code needed):

Call mcp__resources__clerk_list_users with the emailAddress filter:

mcp__resources__clerk_list_users({
    resourceId: "<your-clerk-resource-id>",
    emailAddress: "[e-mail]",
    limit: "10"
})

Using the TypeScript client in a Next.js Server Action:

"use server";

import { clerkClient } from "./clients";

interface ClerkUser {
    id: string;
    first_name: string | null;
    last_name: string | null;
    email_addresses: { email_address: string }[];
    created_at: number;
}

export async function searchUsersByEmail(email: string) {
    const result = await clerkClient.invoke("GET", "/v1/users", "search-users-by-email", {
        query: { email_address: email, limit: "20" },
    });

    if (!result.ok) {
        throw new Error(result.error.message);
    }

    const users = result.result.body.value as ClerkUser[];

    return users.map((u) => ({
        id: u.id,
        name: [u.first_name, u.last_name].filter(Boolean).join(" "),
        email: u.email_addresses[0]?.email_address ?? "",
        createdAt: new Date(u.created_at),
    }));
}

Tips

• Base URL is always https://api.clerk.com — paths should include the version prefix (e.g. /v1/users)
• Auth is automatic — the Secret Key is sent as a Bearer token on every request
• Clerk API version: The connector targets the Clerk Backend API. Refer to Clerk Backend API docs for endpoint details
• Common endpoints: /v1/users, /v1/organizations, /v1/invitations, /v1/sessions, /v1/clients
• Pagination: Most list endpoints support limit and offset query parameters