Princi Plugin

Connect Princi — your personal context engine — to any AI coding tool.

Princi searches your emails, Drive docs, Slack messages, and meeting notes to bootstrap an AI task with the right background. After installing the plugin, ask a question such as “What do I need to do from today's meeting?” or invoke the Princi skill in your client.

Examples:

• “What tasks do I have from today's team sync meeting?”
• “What did we discuss about productionizing Princi in recent meetings?”
• “Create a plan to update the PRD based on our latest discussions.”

Skill invocation syntax varies by client. Claude Code uses /princi:princi, /princi:princi-code-review, and /princi:princi-update-pr-best-practices. In ChatGPT and Codex, you can ask in natural language or select the skill from the plugin.

The context-search workflow works in ChatGPT and Codex. The PR review and best-practices skills also use local Git and GitHub tooling, so run those in a coding client with repository access.

Setup: Claude Code (CLI / Co-work / IDE extension)

Run both inside Claude Code:

/plugin marketplace add princi-ai/princi-plugin
/plugin install princi@princi-plugin

The first Princi tool call opens a browser to sign in. After that, /princi:princi is ready — no API key step.

Setup: Claude Desktop

1. Download princi.mcpb from Releases
2. Double-click to install (or open via Claude Desktop → Extensions) — click Install
3. A browser opens to sign in to Princi
4. Done — Princi's tools are available in conversations

Setup: Cursor

Option A — Install as a Cursor plugin (bundles the skill + MCP server):

In Cursor, run /add-plugin princi — or browse cursor.com/marketplace and install Princi from the listing.

Cursor reads the Agent Plugins package at the repo root — plugin.json, mcp.json, and skills/ — and registers the Princi MCP server and the Princi skills automatically. The first time you invoke a Princi tool, an OAuth browser flow opens to sign in to Princi.

Option B — MCP server only (no plugin):

1. Open Cursor → Settings → MCP
2. Add a new MCP server with URL: https://princi.ai/mcp
3. Save and restart Cursor

Or paste this into your Cursor MCP settings:

{
  "mcpServers": {
    "princi": {
      "type": "http",
      "url": "https://princi.ai/mcp"
    }
  }
}

Auth uses OAuth auto-discovery when Cursor supports it. API-key fallback is available for older clients — contact Princi.

Setup: ChatGPT and Codex

Public Plugins Directory

After Princi is approved and published, find Princi in the Plugins Directory shared by ChatGPT and Codex, install it, and connect your Princi account. This public listing is separate from this repository's marketplace. Until publication, use the local marketplace or developer-mode paths below.

Codex CLI and ChatGPT desktop: repository marketplace

Add this repository as a marketplace and install the plugin:

codex plugin marketplace add princi-ai/princi-plugin
codex plugin add princi@princi-ai

In Codex CLI, start a new session after installation and ask Princi to search your context. In the ChatGPT desktop app, open the Plugins Directory, choose the Princi marketplace, and install Princi. For a full local test with the MCP connection in ChatGPT, register the server and add its connection mapping as described below before installing. The plugin bundles the Agent Plugins package at the repo root — plugin.json, mcp.json, and skills/.

For development from this checkout, run codex plugin marketplace add . instead of the GitHub command, then codex plugin add princi@princi-ai. The desktop app loads an installed copy; restart it and reinstall after changing the local source. Use a new chat to test changed skills or tools.

ChatGPT: direct MCP developer-mode test

To test the MCP tools before the plugin is published:

1. In ChatGPT, open Settings → Security and login and turn on Developer mode.
2. Open ChatGPT Plugins, select +, and register https://princi.ai/mcp.
3. Connect your Princi account, then test the search and fetch tools in a new chat.

This tests the MCP connection. To test a local ChatGPT plugin that combines the connection with bundled skills, copy the registered connection's plugin_asdk_app... ID from its browser URL. Add a local .app.json with your actual ID:

{"apps":{"princi":{"id":"plugin_asdk_app_...","category":"Productivity"}}}

Then add "apps": "./.app.json" beside "interface" under extensions.com.openai in plugin.json. Refresh the desktop app, install from the Princi marketplace, and test in a new chat. Keep this test connection mapping out of the public release. See OpenAI's local plugin guide.

Setup: OpenCode

OpenCode is not an Agent Plugins client, so it needs its own MCP config and a manual skill copy.

Add MCP server. Add Princi MCP to your OpenCode config — ~/.config/opencode/opencode.json for all projects, or opencode.json in a project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "princi": {
      "type": "remote",
      "url": "https://princi.ai/mcp",
      "enabled": true
    }
  }
}

Or copy opencode/opencode.json.

OpenCode detects the server's 401 response and starts the OAuth flow automatically the first time you invoke a Princi tool. To trigger it up front, run opencode mcp auth princi (and opencode mcp logout princi to sign out).

Skills. Install the Princi skills into OpenCode's own skills directory — copy the skills/ folders into ~/.config/opencode/skills/ so each skill lands at ~/.config/opencode/skills/<name>/SKILL.md:

git clone https://github.com/princi-ai/princi-plugin
cd princi-plugin
mkdir -p ~/.config/opencode/skills
cp -R skills/princi skills/princi-code-review skills/princi-update-pr-best-practices ~/.config/opencode/skills/

Then /princi, /princi-code-review, and /princi-update-pr-best-practices are available in OpenCode. (OpenCode can also discover SKILL.md from ~/.claude/skills/, but only on builds after the late-Dec-2025 fix — installing into ~/.config/opencode/skills/ works on every version.)

OpenCode plugins cannot register MCP servers or skills, so there is no plugin bundle to install — the MCP config above plus these skills are the whole setup.

Setup: any Agent Plugins client

The repo root is a conformant Agent Plugins 1.0.0 package, so any compatible client — VS Code, Cursor, GitHub Copilot, Codex, Kiro, Hermes Agent, OpenClaw — can install Princi without a vendor-specific path:

git clone https://github.com/princi-ai/princi-plugin

Then point your client at the clone. It reads three fixed locations from the plugin root — no configuration, no discovery indirection:

The first Princi tool call opens an OAuth browser flow to sign in.

What's left outside the portable package

Cursor and Codex are both compatible clients, so they load skills and MCP from the root package. Cursor can publish from that package alone. The Codex marketplace catalog makes this repository installable as a local or Git marketplace; public ChatGPT/Codex listing uses OpenAI's submission flow. What remains outside the portable package is what the spec leaves to each client:

The spec's portable surface is just skills and MCP servers. Marketplace catalogs, install policy, and signing are explicitly out of scope, so each stays in its platform's own file.

Princi's ai.princi extension remains descriptive metadata for clients that may support it. OpenAI presentation metadata lives separately in extensions.com.openai, so ChatGPT and Codex can show the plugin name, logo, description, and starter prompts.

CI validates plugin.json and mcp.json against the canonical published schemas on every PR. It also checks Agent Skills frontmatter, OpenAI listing metadata, and MCP endpoint consistency. Run the same checks before pushing with ./scripts/validate.sh — it skips checks whose dependencies are missing locally, and CI runs it with STRICT_DEPS=1 so a skip there is a failure.

Troubleshooting

mcp__princi__search not available:

• Re-run the OAuth sign-in flow: invoke a Princi tool — the HTTP MCP client should open a browser to sign in to Princi.
• Restart your coding tool if the sign-in browser doesn't open.

Sign-in browser doesn't open:

• Confirm your coding tool supports OAuth-enabled HTTP MCP servers (Claude Desktop, Claude Code, Codex, Cursor, OpenCode).
• In Codex, force the flow with codex mcp login princi; in OpenCode, opencode mcp auth princi.
• In ChatGPT, open the Princi connection in the Plugins Directory and select Connect.
• Check your terminal/console for an authorization URL printed by mcp-remote and open it manually.

Token expired / 401 errors:

• Sign out by clearing the local mcp-remote token cache at ~/.mcp-auth/ and re-invoke a Princi tool to trigger a fresh sign-in.

0 results from /princi:princi:

• Try a broader or rephrased query
• Ensure your Google/Slack accounts are connected in Princi

Updating

In Claude Code, run /plugin update princi@princi-plugin.

For a Codex Git marketplace installation, run codex plugin marketplace upgrade princi-ai, then codex plugin add princi@princi-ai. Restart the ChatGPT desktop app or begin a new Codex session before testing the updated plugin.

Verify a Release

Each release ships a princi-<version>-checksums.txt file with SHA256 hashes for every artifact. After downloading, verify with:

sha256sum -c princi-v0.1.0-checksums.txt

What the plugin can access

Installing this plugin grants identity only — the MCP server requests openid, profile, and email. No Gmail, Drive, Slack, or Calendar scope. Verify against the server's public metadata:

curl -s https://princi.ai/.well-known/oauth-protected-resource
# "scopes_supported": ["openid", "profile", "email"]

Sources are connected separately in the Princi app at princi.ai, under their own consent screen. Those grants belong to your account, not this plugin, so uninstalling does not disconnect them — revoke them in the app.

Privacy Policy

Data collected. Princi receives an OAuth identity (your Supabase Auth subject) and the MCP tool invocations you make against the Princi server — search queries and the IDs you fetch.

Use. This data is used solely to authenticate you and to return search/fetch results from your indexed sources (Gmail, Drive, Slack, Calendar, memory).

Storage. OAuth tokens are encrypted at rest in Supabase. Your indexed corpora are stored per-user.

Third-party sharing. None beyond the user's own connected providers (e.g., Google, Slack) that you have explicitly authorized.

Retention. Data is retained for the lifetime of your account and is revocable at any time via princi.ai.

Contact. Reach us at support@princi.ai for any privacy questions or data deletion requests.

Full policy: https://princi.ai/privacy