API, MCP, CLI, and SDKs for Convex. Open-source software maintained by Yast AI.
Define an internal Convex function once. Choose its interfaces. Keep validation, business logic and authorization in the same function.
Convex internal functions + validators + platforms metadata
↓
Local generation
↓
One versioned application contract
↓
HTTP API · MCP tools · CLI · TypeScript/Python SDKs
Reusable WorkOS account and team functions for Convex, with authenticated APIs, MCP tools, CLIs and SDKs.
2026-10-28
星标
—
工具
—
可用率
—
Optional WorkOS account and team operations supply native account, membership, invitation, API-key and team functions, including public wrappers and personal organization provisioning. Configure them in one Convex file and export only the operations you want; your own account/team functions can replace any builtin.
Optional MCP Apps attach your React UI to tools. Optional project-level plugins bundle skills and MCP configuration for OpenAI and Claude. Plugins are separate from function-level interface selection.
Requires an existing Convex project, Bun 1.3+, Node 22.14+, and a WorkOS AuthKit environment. New to either service? Start with the three onboarding paths.
bun add @disposabl/convex-platforms
bunx convex-platforms init --name my-app
For account/team operations and custom business functions together, use one createPlatforms integration in convex/platforms.ts. It supplies the typed internal builders, selected native WorkOS operations and HTTP routes. Export only the operations you need; your own functions can replace any builtin. The factory reads no credentials and imports no generated files during discovery.
Mount it alongside application routes in convex/http.ts:
import type { Manifest } from '@disposabl/convex-platforms';
import manifest from '../platforms/generated/manifest.json';
import { registerRoutes } from './platforms';
registerRoutes(http, manifest as Manifest);
The initializer creates this single typed integration, a bootstrap manifest, setup instructions and generation scripts. It preserves existing authentication and HTTP routes. No account/team builtin is exported by default. Configure your WorkOS roles and a trusted authentication callback before exporting optional public aliases. The omitted callback rejects all public calls.
Use the new internal builders in a feature folder:
// convex/todos/internal.ts
import { ConvexError, v } from 'convex/values';
import { internalMutation, identityFields } from '../platforms';
export const createTodo = internalMutation({
platforms: true,
description: 'Create a todo in the authenticated organization',
args: { ...identityFields, text: v.string() },
returns: v.id('todos'),
handler: async (ctx, { orgId, userId, text }) => {
const value = text.trim();
if (!value || value.length > 200) {
throw new ConvexError({ code: 'invalid_text', status: 400 });
}
return ctx.db.insert('todos', { orgId, userId, text: value });
},
});
The app owns its schema. Add a todos table with orgId, userId and text fields, and indexes for collection reads. Existing public web functions can call this same internal function after resolving their authenticated identity.
bun run ports:generate
bunx convex dev
Before that first deployment, set WORKOS_CLIENT_ID, WORKOS_API_KEY, and the trusted public AuthKit origin WORKOS_AUTHKIT_URL on the selected Convex deployment. Missing settings prevent route initialization. Follow platforms/SETUP.md for authentication wiring.
Generate before every deployment. Keep generated outputs out of source control and regenerate in CI. Generation never deploys or creates provider accounts.
Choose interfaces
Metadata
Result
omitted, false, or {}
No generated interfaces
true
API, MCP, CLI and both SDKs
{ mcp: true }
MCP only
{ api: true, 'sdk-typescript': true }
API and TypeScript SDK
{ cli: true, 'sdk-python': true }
CLI and Python SDK, with authenticated HTTP transport
Public Convex wrappers remain independent. Interface selection does not grant permission to execute an operation.
Names derive from feature folders and function names. Optional resource: ['account', 'members'] metadata sets a logical namespace independently of the file, so several resources can share one Convex module:
Source
HTTP
MCP
CLI
SDK
todos/internal.ts:createTodo
/api/v1/todos/create
todos_create
todos create
client.todos.create
members/actions.ts:updateMemberRole
/api/v1/members/updateRole
members_update_role
members update-role
TS updateRole, Python update_role
Arguments are flat JSON objects. Authentication fields never appear in generated input schemas.
Authentication
Set server-side WORKOS_CLIENT_ID, WORKOS_API_KEY, and WORKOS_AUTHKIT_URL on the correct Convex deployment. CONVEX_SITE_URL is supplied by Convex. Keep credentials out of client bundles and generated artifacts.
Configure Convex JWT verification using getWorkOSAuthProviders from @disposabl/convex-platforms/oauth. Preserve existing providers when integrating an existing app. WorkOS Connect must also enable Client ID Metadata Documents, known as CIMD, and register the exact deployment /mcp URL as a resource indicator. Detailed setup.
The HTTP runtime validates WorkOS user API keys with api:access, or accepts a verified WorkOS session. MCP uses WorkOS Connect with its exact issuer and resource audience. Every authenticated request resolves current active organization membership and forwards trusted flat orgId, userId, role fields to the internal function. App functions still enforce organization isolation and resource ownership.
Custom WorkOS roles are supported. Configure rolePriority when your membership may have multiple roles; the package does not invent an administrator role.
CLI and SDKs
The shared CLI discovers available commands from your deployment:
For automation, supply CONVEX_PLATFORMS_TOKEN through your secret manager. Device login stores only private, origin-scoped refresh credentials and serializes rotating refreshes. WorkOS chooses the organization; the CLI provides no organization override.
Add your UI entry at platforms/ui/todos.html and platforms/ui/todos.tsx, then set ui: 'todos' on an MCP-enabled function. Generation bundles a standalone HTML resource with a content hash. UI guide.
Package app-level skills and host manifests after generation:
The command creates separate OpenAI and Claude bundles pointing to the same MCP endpoint. Supply curated project skills in skills/ before packaging. Packaging does not submit to a public directory or guarantee host approval. Plugin distribution.
Test before deploying
bun run ports:check
bunx convex-platforms --site-url https://YOUR-DEPLOYMENT.convex.site doctor
doctor checks public discovery/configuration and the unauthenticated MCP challenge. A passing result does not prove an authorized user can execute a tool. Run authenticated positive and negative checks in the intended hosts. Local and deployed verification.
For contributors:
bun install --frozen-lockfile
bun run format
bun run lint
bun run typecheck
bun test
bun run build
MIT licensed. Convex Platforms is an independent Yast AI project. Convex, WorkOS, OpenAI and Anthropic are the respective providers of the services it integrates with.