{"_id":"@xmcp-dev/workos","_rev":"3-b5755d170ad95c966e07a5b77491f509","name":"@xmcp-dev/workos","dist-tags":{"latest":"1.0.1"},"versions":{"0.0.1":{"name":"@xmcp-dev/workos","version":"0.0.1","keywords":["xmcp","workos","authkit","authentication","mcp","oauth"],"author":{"url":"https://xmcp.dev","name":"xmcp","email":"support@xmcp.dev"},"license":"MIT","_id":"@xmcp-dev/workos@0.0.1","maintainers":[{"name":"valentinabearzotti","email":"valebearzotti1@gmail.com"},{"name":"joserago","email":"jose@basement.studio"}],"homepage":"https://xmcp.dev","bugs":{"url":"https://github.com/basementstudio/xmcp/issues"},"dist":{"shasum":"d26e45a8f9207b1349a6939daa35a8961ae42dd6","tarball":"https://registry.npmjs.org/@xmcp-dev/workos/-/workos-0.0.1.tgz","fileCount":34,"integrity":"sha512-zzwR50UMOvDa8pVhMA8GseWKx9yBXsf2vXxIiaN+RFZzeoOSmmf12YA4pPCk+PQ3O6NGVumbZWF0RbRdIKpSbw==","signatures":[{"sig":"MEQCIHIbiNFvuwwwWt7kM1FS2B4uBaggE+DpCPEFmSNa4gUKAiAl4Ug0gcOaN8P5GUuFaCbOigKx3RWLxQeLOFHOal+6eA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":173959},"main":"./dist/index.js","type":"module","_from":"file:xmcp-dev-workos-0.0.1.tgz","types":"./dist/index.d.ts","scripts":{"dev":"tsc --watch","build":"rm -rf dist && tsc"},"_npmUser":{"name":"valentinabearzotti","email":"valebearzotti1@gmail.com"},"_resolved":"/tmp/56f6f6770d1e160a2e1718e7dce88632/xmcp-dev-workos-0.0.1.tgz","_integrity":"sha512-zzwR50UMOvDa8pVhMA8GseWKx9yBXsf2vXxIiaN+RFZzeoOSmmf12YA4pPCk+PQ3O6NGVumbZWF0RbRdIKpSbw==","repository":{"url":"git+https://github.com/basementstudio/xmcp.git","type":"git","directory":"packages/plugins/workos"},"_npmVersion":"10.8.2","description":"WorkOS AuthKit integration for xmcp","directories":{},"_nodeVersion":"20.19.6","dependencies":{"jose":"^5.2.0","express":"^4.22.1","@workos-inc/node":"^7.79.3"},"_hasShrinkwrap":false,"devDependencies":{"xmcp":"^0.5.7","typescript":"^5.9.3","@types/node":"^22.19.2","@types/express":"^5.0.6"},"peerDependencies":{"xmcp":"^0.5.7"},"_npmOperationalInternal":{"tmp":"tmp/workos_0.0.1_1767731139351_0.503960205615323","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@xmcp-dev/workos","version":"0.0.2","keywords":["xmcp","workos","authkit","authentication","mcp","oauth"],"author":{"url":"https://xmcp.dev","name":"xmcp","email":"support@xmcp.dev"},"license":"MIT","_id":"@xmcp-dev/workos@0.0.2","maintainers":[{"name":"valentinabearzotti","email":"valebearzotti1@gmail.com"},{"name":"joserago","email":"jose@basement.studio"}],"homepage":"https://xmcp.dev","bugs":{"url":"https://github.com/basementstudio/xmcp/issues"},"dist":{"shasum":"1e5f62d9e104155e4e5c650c9ebefae524f6bdec","tarball":"https://registry.npmjs.org/@xmcp-dev/workos/-/workos-0.0.2.tgz","fileCount":34,"integrity":"sha512-lIyEjQGQSi9Ie3dXhDMxa4PpwALmCuzs50I8GPlAuNhdU4U60Cy0sD515pvBlpaF/ipS2XxoJSTHxbctdxQVew==","signatures":[{"sig":"MEYCIQD22NOAdFjOW+hNfzVLXk1fKvy0Xnw3dB8CQjgkWQrjfQIhAIHdtfw3e0YGJ9h0rSTJQR0O3U9i26ozgQ3HBIwT1BEp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":33855},"main":"./dist/index.js","type":"module","_from":"file:xmcp-dev-workos-0.0.2.tgz","types":"./dist/index.d.ts","scripts":{"dev":"tsc --watch","build":"rm -rf dist && tsc"},"_npmUser":{"name":"valentinabearzotti","email":"valebearzotti1@gmail.com"},"_resolved":"/tmp/614d264f7cd353fba3e21a5df6f09091/xmcp-dev-workos-0.0.2.tgz","_integrity":"sha512-lIyEjQGQSi9Ie3dXhDMxa4PpwALmCuzs50I8GPlAuNhdU4U60Cy0sD515pvBlpaF/ipS2XxoJSTHxbctdxQVew==","repository":{"url":"git+https://github.com/basementstudio/xmcp.git","type":"git","directory":"packages/plugins/workos"},"_npmVersion":"10.8.2","description":"WorkOS AuthKit integration for xmcp","directories":{},"_nodeVersion":"20.19.6","dependencies":{"jose":"^5.2.0","express":"^4.22.1","@workos-inc/node":"^7.79.3"},"_hasShrinkwrap":false,"devDependencies":{"xmcp":"^0.5.7","typescript":"^5.9.3","@types/node":"^22.19.2","@types/express":"^4.17.25"},"peerDependencies":{"xmcp":"^0.5.7"},"_npmOperationalInternal":{"tmp":"tmp/workos_0.0.2_1767891443062_0.8530519659877833","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@xmcp-dev/workos","description":"WorkOS AuthKit integration for xmcp","version":"1.0.1","author":{"name":"xmcp","email":"support@xmcp.dev","url":"https://xmcp.dev"},"license":"MIT","keywords":["xmcp","workos","authkit","authentication","mcp","oauth"],"repository":{"type":"git","url":"git+https://github.com/basementstudio/xmcp.git","directory":"packages/plugins/workos"},"homepage":"https://xmcp.dev","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","dependencies":{"@workos-inc/node":"^7.79.3","jose":"^5.2.0","express":"^4.22.1"},"devDependencies":{"@types/express":"^5.0.6","@types/node":"^22.19.2","typescript":"^5.9.3","xmcp":"1.1.1"},"peerDependencies":{"xmcp":">=1.0.0"},"scripts":{"dev":"tsc --watch","build":"rm -rf dist && tsc"},"_id":"@xmcp-dev/workos@1.0.1","bugs":{"url":"https://github.com/basementstudio/xmcp/issues"},"_integrity":"sha512-0PneQlrgy0ELSH3Ck6fWTMAOxetXBaAwpkguLCS6Om9DN3A1HwHZgowAWXhMuxTNJXGPOJ16XHPS+U/SK3+mdQ==","_resolved":"/tmp/80f378d8f30f0a2ec4ae1610129c4e99/xmcp-dev-workos-1.0.1.tgz","_from":"file:xmcp-dev-workos-1.0.1.tgz","_nodeVersion":"22.14.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-0PneQlrgy0ELSH3Ck6fWTMAOxetXBaAwpkguLCS6Om9DN3A1HwHZgowAWXhMuxTNJXGPOJ16XHPS+U/SK3+mdQ==","shasum":"91bcaf6d1f0a9137a8227657f0725301132b984e","tarball":"https://registry.npmjs.org/@xmcp-dev/workos/-/workos-1.0.1.tgz","fileCount":34,"unpackedSize":31908,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@xmcp-dev%2fworkos@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIACYb/Mk37DX0EJr2GN1CjggYEVmtWpOD3of2QxRwAU5AiEAtBfNgKVHmw7j7mGdcH+20VDyeVcaYsgn4hFMyzis3hM="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:8a9e7974-e09b-4913-ad8d-c6303eb98054"}},"directories":{},"maintainers":[{"name":"valentinabearzotti","email":"valebearzotti1@gmail.com"},{"name":"joserago","email":"jose@basement.studio"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/workos_1.0.1_1787563353610_0.39895383532536166"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-06T20:25:39.226Z","modified":"2026-08-24T09:22:34.143Z","0.0.1":"2026-01-06T20:25:39.498Z","0.0.2":"2026-01-08T16:57:23.193Z","1.0.1":"2026-08-24T09:22:33.730Z"},"bugs":{"url":"https://github.com/basementstudio/xmcp/issues"},"author":{"name":"xmcp","email":"support@xmcp.dev","url":"https://xmcp.dev"},"license":"MIT","homepage":"https://xmcp.dev","keywords":["xmcp","workos","authkit","authentication","mcp","oauth"],"repository":{"type":"git","url":"git+https://github.com/basementstudio/xmcp.git","directory":"packages/plugins/workos"},"description":"WorkOS AuthKit integration for xmcp","maintainers":[{"name":"valentinabearzotti","email":"valebearzotti1@gmail.com"},{"name":"joserago","email":"jose@basement.studio"}],"readme":"# @xmcp-dev/workos\n\nWorkOS AuthKit integration for xmcp MCP servers. Enables OAuth 2.0 authentication for MCP clients using WorkOS Connect.\n\n## Installation\n\n```bash\nnpm install @xmcp-dev/workos\n# or\npnpm add @xmcp-dev/workos\n```\n\n## WorkOS Setup\n\nBefore using this plugin, we need to get some values and enable some options in our WorkOS application:\n\n1. Go to your [WorkOS Dashboard](https://dashboard.workos.com)\n2. In the **Overview** page, under **Quickstart**, you will find `WORKOS_API_KEY` and `WORKOS_CLIENT_ID`, save these values.\n3. Go to **Domains** and save the AuthKit domain, it looks like this `https://xxx.authkit.app`.\n4. Navigate to **Connect** and then **Configuration** to enable the following options that are inside **MCP Auth** settings:\n   - **Client ID Metadata Document (CIMD)**\n   - **Dynamic Client Registration (DCR)**\n\n## Usage\n\n### 1. Configure the middleware\n\nCreate a `middleware.ts` file in your xmcp project:\n\n```typescript\nimport { workosProvider } from \"@xmcp-dev/workos\";\n\nexport default workosProvider({\n  apiKey: process.env.WORKOS_API_KEY!,\n  clientId: process.env.WORKOS_CLIENT_ID!,\n  baseURL: process.env.BASE_URL!,\n  authkitDomain: process.env.WORKOS_AUTHKIT_DOMAIN!,\n  // Optional: Link to your API documentation\n  docsURL: \"https://yourserver.com/docs/mcp\",\n});\n```\n\n### 2. Environment Variables\n\n```bash\nWORKOS_API_KEY=sk_...\nWORKOS_CLIENT_ID=client_...\nWORKOS_AUTHKIT_DOMAIN=yourcompany.authkit.app\n\nBASE_URL=http://127.0.0.1:3001\n```\n\n### 3. Access Session in Tools\n\n```typescript\nimport { getSession, getUser } from \"@xmcp-dev/workos\";\n\nexport default async function myTool() {\n  // Get session data from JWT (fast, no API call)\n  const session = getSession();\n  console.log(session.userId);\n  console.log(session.organizationId);\n  console.log(session.role);\n  console.log(session.permissions);\n\n  // Get full user data from WorkOS API\n  const user = await getUser();\n  console.log(user.email);\n  console.log(user.firstName);\n  console.log(user.lastName);\n\n  return `Hello ${user.firstName}! Your user ID is ${session.userId}`;\n}\n```\n\n## API Reference\n\n### `workosProvider(config)`\n\nCreates the WorkOS middleware and router for xmcp.\n\n**Config:**\n- `apiKey` - WorkOS API key\n- `clientId` - WorkOS Client ID\n- `baseURL` - Base URL of your MCP server\n- `authkitDomain` - AuthKit domain\n- `docsURL` - (Optional) URL for your MCP server documentation\n\n### `getSession()`\n\nReturns the current session from JWT claims. Throws if not authenticated.\n\n**Returns:** `Session`\n- `userId` - WorkOS user ID\n- `sessionId` - Session ID\n- `expiresAt` - Token expiration date\n- `issuedAt` - Token issued date\n- `claims` - Raw JWT claims\n\n### `getUser()`\n\nFetches full user data from WorkOS API using the SDK.\n\n**Returns:** WorkOS `User` object with email, name, profile picture, etc.\n\n### `getClient()`\n\nReturns the initialized WorkOS SDK client for advanced use cases.\n\n## Using the WorkOS SDK\n\nThe `getClient()` function gives you access to the full [WorkOS Node SDK](https://workos.com/docs/sdks/node), allowing you to leverage all WorkOS features in your MCP tools.\n\n### User Management\n\n```typescript\nimport { getSession, getClient } from \"@xmcp-dev/workos\";\n\nexport default async function myTool() {\n  const session = getSession();\n  const workos = getClient();\n\n  // List organization memberships\n  const memberships = await workos.userManagement.listOrganizationMemberships({\n    userId: session.userId,\n  });\n\n  // Update user metadata\n  await workos.userManagement.updateUser(session.userId, {\n    firstName: \"Updated Name\",\n  });\n\n  return \"Done!\";\n}\n```\n\n### Organizations\n\n```typescript\nconst workos = getClient();\nconst session = getSession();\n\n// Get organization details\nif (session.organizationId) {\n  const org = await workos.organizations.getOrganization(session.organizationId);\n  console.log(org.name, org.domains);\n}\n\n// List all organizations\nconst orgs = await workos.organizations.listOrganizations();\n```\n\n### Directory Sync (SCIM)\n\n```typescript\nconst workos = getClient();\n\n// List directory users\nconst users = await workos.directorySync.listUsers({\n  directory: \"directory_xxx\",\n});\n\n// List groups\nconst groups = await workos.directorySync.listGroups({\n  directory: \"directory_xxx\",\n});\n```\n\n### Audit Logs\n\n```typescript\nconst workos = getClient();\nconst session = getSession();\n\n// Create an audit log event\nawait workos.auditLogs.createEvent({\n  organizationId: session.organizationId,\n  event: {\n    action: \"document.viewed\",\n    actor: { id: session.userId, type: \"user\" },\n    targets: [{ id: \"doc_123\", type: \"document\" }],\n  },\n});\n```\n\n### Token Lifecycle\n\n- Access tokens are short-lived\n- MCP clients automatically refresh tokens using refresh tokens\n- If you see \"token_expired\" errors, the client should handle refresh automatically","readmeFilename":"README.md"}