Pearl

Pearl agent integration package

New to Pearl? Start with the Quick Start & Tester Guide.

Eligible Pearl Reserve and Elite members can connect. Available actions depend on the connection's permissions and live tool inventory.

Pearl's installable package gives Codex, Claude, Cursor, and Cursor's Grok Bot a thin host integration for one authenticated Streamable HTTP MCP endpoint:

https://agent.joinpearl.co/mcp

The package contains host manifests, the Pearl Concierge skill, public setup documentation, brand assets, presentation-only MCP Apps resources, and validation code. It contains no application, database, OAuth server, MCP executor, deployment configuration, access token or client secret.

Current release

Package 0.13.0 keeps the common 13 reads for every authenticated connection. Reviewed Codex, Claude and Cursor clients also get table availability, six discovery reads (venue details, when bookings open, similar and nearby places, Pearl events, and the bookable venues of a Tables city) and ten confirmed-action tools for visits, saved places and private trips: 20 tools with the seven reads, 30 with all ten scopes. The discovery reads need no new permission; reconnect to approve newly requested permissions. ChatGPT retains its submitted 18-tool visit/availability contract. The CLI defaults to 13 reads; unknown clients remain read-only. Selected Codex, Claude, Cursor and CLI registrations can also receive four confirmed record-import pairs after rollout and relevant consent. These record flights, recorded seats, existing reservations and visit items, without provider actions. CLI publication is separate.

Current Codex presents the shared OpenAI-hosted CIMD client ID (older releases used per-install identities); Pearl accepts only that strictly validated official family. The same gateway and executor serve every host. Cards are presentation-only and cover venues, saved places, visits, place matches, your profile, trips, reservations, venue details, availability, flights where available, and visit/save/trip previews and receipts.

See the capability snapshot for the exact host matrix and honest unavailable-workflow labels. No host can book, hold, change, cancel, or pay for a reservation in this release. The package does not claim that a host has approved or listed Pearl.

For practical logging/editing prompts, matching and confirmation rules, and reservation boundaries, see Visits and reservations.

Included artifacts

• .codex-plugin/plugin.json: Codex metadata and starter prompts.
• .claude-plugin/plugin.json: Claude Code and Cowork metadata.
• cursor/.cursor-plugin/plugin.json: the isolated Cursor source plus the host-specific pearl-cursor identifier and secretless public OAuth configuration.
• .mcp.json: the single shared URL-only Codex and Claude connection; Cursor's isolated thin wrapper uses the same endpoint with its required static public client.
• server.json: the MCP Registry preview entry for the same remote URL; it contains no headers, credentials, package runtime, or tool inventory.
• skills/pearl-concierge/: the canonical discovery-first workflow skill for Codex and Claude; Cursor ships a byte-for-byte validated mirror under its isolated source subtree.
• docs/: member setup, host registration and review, OAuth, and release instructions.
• assets/: approved Pearl marketplace artwork; see assets/README.md. Cursor's isolated source contains a hash-validated logo mirror.
• mcp-apps/: the dependency-free, versioned inline UI resource and integration helpers. It adds no tools, auth, network endpoint, or business logic; see mcp-apps/README.md.
• scripts/ and test/: zero-dependency validation.

Validate

From the repository root:

npm --prefix plugins/pearl test

npm --prefix plugins/pearl run validate npm --prefix plugins/pearl run validate:live npm --prefix plugins/pearl run validate:registry npm --prefix plugins/pearl run validate:registry:schema npm --prefix plugins/pearl run validate:registry:live claude plugin validate plugins/pearl --strict claude plugin validate . --strict

Live validation performs only public discovery and unauthenticated challenge checks. It does not use credentials or invoke member tools.

Pearl maintainers who have Codex's bundled plugin-creator and skill-creator skills installed should additionally run those skills' validators against plugins/pearl and both packaged Pearl Concierge skill directories. These are maintainer checks, not public package dependencies.

Before a marketplace release, also run the safe static-host registration probes documented in docs/submission.md. Those probes use an intentionally invalid MCP resource and never create an authorization request or invoke a member tool.

The official MCP Registry is in preview. Keeping server.json in the package does not publish it or imply Registry, Anthropic, Cursor, or OpenAI approval. Registry publication is a separate protected release action documented in docs/releasing.md.

Security and support

Never add credentials, environment files, authorization headers, private implementation details, or member data to this package. Report vulnerabilities privately to hello@joinpearl.co with [Security] in the subject line.

• Member setup: docs/setup.md
• Host registration and review: docs/host-operators.md
• OAuth: docs/oauth.md
• Releases: docs/releasing.md
• Host submission: docs/submission.md
• Privacy: https://joinpearl.co/privacy
• Terms: https://joinpearl.co/terms
• Support: https://joinpearl.co/support