TeamShared MCP server

teamshared (Cursor, Claude Code, and Codex plugins)

Registers the teamshared MCP server. The Cursor plugin also ships the recall-first memory rule and Cursor hooks that capture Agent Chat into TeamShared (sessionStart, beforeSubmitPrompt, afterAgentResponse, stop, sessionEnd) plus postToolUse (failed test/lint/shell), postToolUseFailure (read-only recall), and preCompact. The Cursor plugin still has no skills, slash commands, or extra agents.

This repo also ships a Claude Code marketplace plugin under claude/ (remote MCP via Claude Code's native /mcp OAuth, TEAMSHARED_TOKEN for the optional capture hooks, protocol 1.31.0, SessionStart injection, and official Claude Code capture hooks).

The native Codex package under plugins/teamshared/ uses the server's MCP OAuth discovery flow and treats Codex as a first-class client: protocol 1.31.0, SessionStart injection, and official Codex capture hooks. A manual Codex TOML setup remains available under install/codex/ (TEAMSHARED_TOKEN; do not mix).

Hosted install is teamshared.com/#connect. The public plugin / marketplace source is this repo (teamshared-ai/teamshared-plugin). The remote MCP endpoint is https://teamshared.com/mcp.

One Connect, one org per repo. Install the plugin once and connect once. From chat, call org_list / org_bind(slug=...). CLI teamshared org bind <slug> is an optional fallback that writes .teamshared/org. Do not add a second TeamShared server. Unbound /mcp keeps working — it stays on the org chosen at Connect time. Agent-facing copy: AGENTS.md.

Component	Purpose
mcp.json	Registers https://teamshared.com/mcp (URL only; Cursor OAuth Connect)
rules/teamshared.mdc	Lean always-on fetch/store loop (alwaysApply); tool encyclopedia lives in memory_tools_catalog
hooks/	Cursor hooks: Agent Chat capture plus postToolUse (failed test/lint/shell), postToolUseFailure (read-only recall), and preCompact
claude/	Claude Code plugin (remote MCP via native /mcp OAuth + protocol 1.31.0 + capture hooks needing TEAMSHARED_TOKEN)
.claude-plugin/marketplace.json	Claude Code marketplace catalog (/plugin marketplace add teamshared-ai/teamshared-plugin)
.agents/plugins/marketplace.json	Codex marketplace catalog (codex plugin marketplace add teamshared-ai/teamshared-plugin)
plugins/teamshared/	Native Codex plugin (OAuth MCP + protocol 1.31.0 + official capture hooks)
clients/	Copy-paste protocol + MCP examples for non-Cursor harnesses (not loaded by Cursor)

Install

From git marketplace (recommended)

1. Settings → Plugins → Add marketplace → paste https://github.com/teamshared-ai/teamshared-plugin
2. Run /add-plugin teamshared or enable teamshared under Settings → Plugins
3. Settings → Tools & MCP → teamshared → Connect (email + one-time code, same as the console)

Cloud and Grok Bot agents inherit that account-level Connect. Installing the plugin registers https://teamshared.com/mcp — you only click Connect. Do not paste a URL or token into the plugin mcp.json. Then bind the repo (teamshared org bind <slug>); do not add a second TeamShared server.

See MARKETPLACE.md for the official Marketplace publish checklist.

Claude Code (marketplace)

/plugin marketplace add teamshared-ai/teamshared-plugin
/plugin install teamshared@teamshared
/reload-plugins
/mcp

In /mcp, select teamshared and choose Authenticate — Claude Code's own native OAuth flow, same email/OTP login as the web console, token stored in your system keychain. Confirm tools appear under /mcp as plugin:teamshared:teamshared connected.

The chat-capture hooks are a separate subprocess with no access to that keychain, so if you also want them capturing chat automatically, mint a tsk_ org key and export it — never commit it:

export TEAMSHARED_TOKEN=tsk_...   # mint under https://teamshared.com/app/keys

Without it the hooks just no-op; the MCP connection and every-turn workflow work fine either way. From chat, call org_bind(slug=...) (CLI teamshared org bind <slug> is optional) so capture follows the org; do not add a project .mcp.json TeamShared server. Unbound /mcp keeps working. SessionStart injects protocol 1.31.0; /teamshared:status checks health + version. Details: claude/README.md.

Codex (native plugin marketplace)

The native Codex package uses TeamShared's MCP OAuth discovery flow, so it does not require TEAMSHARED_TOKEN or store an authorization header. The first browser open is the Codex host (system default browser). TeamShared only serves /oauth/authorize and the redirect; the post-OTP finish page uses a single handoff. ChatGPT’s in-app @Browser is Computer Use, not MCP Authenticate — there is no API to force Connect there. To skip the browser, use install/codex/ + TEAMSHARED_TOKEN instead of this plugin. Details: #46 and plugins/teamshared/README.md.

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

Restart the Codex app, start a new task, and connect TeamShared when prompted. Then review and trust plugin hooks with /hooks so capture writes run. From chat, call org_bind(slug=...) (CLI teamshared org bind <slug> is optional); do not add a second [mcp_servers.teamshared] next to the plugin. Unbound /mcp keeps working. SessionStart injects protocol 1.31.0; $status checks health + version. The package lives under plugins/teamshared/ and is cataloged by .agents/plugins/marketplace.json. Details: plugins/teamshared/README.md.

cursor.directory listing

Submit this repo at cursor.directory/plugins/new:

https://github.com/teamshared-ai/teamshared-plugin

Do not submit the old xhad/teamshared-cursor redirect. Root plugin.json and .mcp.json are the Open Plugins / directory discovery files; Cursor install still uses .cursor-plugin/ and mcp.json.

Ready-to-paste listing description:

TeamShared is hosted MCP plus the recall-first memory rule and Cursor
hooks that capture Agent Chat (plus failed test/lint/shell + preCompact).
No skills, slash commands, or extra agents.

Install in Cursor:
1. Settings → Plugins → Add marketplace
2. Paste https://github.com/teamshared-ai/teamshared-plugin
3. /add-plugin teamshared
4. Settings → Tools & MCP → teamshared → Connect (email + one-time code)

Cloud and Grok Bot agents inherit that Connect.
Bind each repo with teamshared org bind; do not add a second server.

From this repo (folder or symlink)

Add plugins from folder needs a marketplace catalog in the selected directory. Select this repo root (it ships .cursor-plugin/marketplace.json with "source": "./").

Then enable the plugin, reload the window, and Connect.

For local iteration without the folder picker:

ln -sf "$(pwd)" ~/.cursor/plugins/local/teamshared

Setup

1. Connect with email/OTP — Settings → Tools & MCP → teamshared → Connect. Cursor opens a browser; sign in with the same email + one-time code as the web console (/app). The plugin already shipped the server URL; do not add headers or a tsk_* token to the plugin mcp.json.
2. Bind the repo — teamshared org bind <slug> writes .teamshared/org ({"v":1,"slug"}). Commit that file. Capture follows it. Do not add a second TeamShared server in .cursor/mcp.json, project .mcp.json, or Codex config.toml.
3. Cursor Cloud / Grok Bot — they inherit that account-level Cursor Connect. After the one-time Connect, every cloud agent for that user gets TeamShared. Bind still lives in the checkout (.teamshared/org); Cloud does not take a second MCP URL from repo config. Unbound /mcp keeps working (Connect-time org).
4. Developer: Reload Window — confirm Settings → MCP shows teamshared enabled.

If you previously added https://teamshared.com/mcp by hand, remove that manual entry so you do not get two teamshared servers.

Bots that must stay in one org use a seat key — teamshared token mint scoped to that org, or mint under /app/keys — on the MCP headers (Authorization: Bearer tsk_…). Not in the plugin mcp.json. Unbound /mcp keeps working for interactive Connect.

What you get

• MCP tools: memory_recall, memory_remember, memory_session_*, etc. (registered by mcp.json when the plugin is installed).
• Rule: injects the recall-first protocol on every agent turn, and points teammates to the web console (/app) for human actions.
• Cursor hooks: Agent Chat turns are appended to TeamShared in near-real-time without waiting for the agent to call memory_session_ensure / context_commit. sessionStart maps conversation_id onto a working session and, after a successful ensure with auto_recall=true, injects a capped Cursor additional_context block (linked soul, a short playbook header when present, and compact auto_recall bullets — not full memory bodies or transcripts). Explicit memory_recall remains preferred for keyword work. Fail-open on MCP/auth errors. beforeSubmitPrompt and afterAgentResponse append redacted user/assistant text; sessionEnd closes and distills. stop only notes aborted/error loops (it fires after every turn, so it does not distill). postToolUse still appends a short episodic fact when a Shell test/lint/command fails (command + error tail, secrets stripped). On Cursor postToolUseFailure and on that failed postToolUse, hooks also call remote memory_recall with a tight query (tool name + truncated error, k=3, verbose=false) and inject compact hits as additional_context — same pattern as SessionStart auto_recall. Skip when recall is empty or MCP has no token. That recall path never writes (context_commit). Fail-open if MCP is unreachable. preCompact writes a short session summary. All reuse the existing Connect session — no tsk_ in mcp.json. Cloud agents may skip sessionStart / sessionEnd; prompt/response hooks still capture turns. Agents still recall first and may commit curated facts; hooks store the transcript.

Bind a repo to an org

One TeamShared server stays on https://teamshared.com/mcp. The repo file chooses the org; capture follows it. Do not add a second TeamShared server.

teamshared org bind sapien --token "$TEAMSHARED_TOKEN"
teamshared org status
teamshared org unbind

bind checks membership, then writes only .teamshared/org:

{"v":1,"slug":"sapien"}

The derived URL https://teamshared.com/o/{slug}/mcp is never stored. Commit the file so every harness in the checkout sees the same org. status and unbind work offline. Missing or invalid file → unbound /mcp (Connect-time org). That is supported; binding is not required.

Harness	Connect once	Bind	Do not
Cursor	Settings → Tools & MCP → teamshared → Connect	.teamshared/org; hooks POST to the org URL with the same Connect token	.cursor/mcp.json / project MCP twin
Cursor Cloud	Inherited account Connect	Same checkout file; hooks follow it	Repo MCP URL as a Cloud bind path
Claude Code	/mcp → Authenticate	Same file; hooks use an org-scoped TEAMSHARED_TOKEN	Project .mcp.json TeamShared server
Codex	Plugin OAuth (or manual tsk_ — not both)	Same file	[mcp_servers.teamshared] next to the plugin

Bots that must stay in one org: teamshared token mint <agent> (org-scoped seat key) or /app/keys. Still one server.

The Cursor plugin still has no skills, slash commands, or extra agents. The Claude Code package ships protocol 1.31.0 (teamshared-memory), /teamshared:status, and official Claude Code capture hooks. The Codex package ships the same 1.31.0 loop plus official Codex hooks (SessionStart, UserPromptSubmit, Stop, Interrupt, SessionEnd, PostToolUse on failed Bash, PreCompact). SessionEnd closes through one bounded commit; Interrupt covers Cursor abort parity. Codex has no StopFailure or PostToolUseFailure.

Other clients

See clients/ for Hermes, Claude Desktop, and protocol markdown. Claude Code and Codex should use their marketplace plugins above unless you are debugging a manual client configuration.

Codex (manual TOML alternative)

For manual MCP registration without the native plugin, Codex uses TOML rather than Cursor's JSON mcp.json. Mint a tsk_ key at teamshared.com/app/keys, export it, then register the hosted MCP (Codex sends Authorization: Bearer tsk_…):

export TEAMSHARED_TOKEN=tsk_...   # from /app/keys — never commit this
codex mcp add teamshared \
  --url https://teamshared.com/mcp \
  --bearer-token-env-var TEAMSHARED_TOKEN

Or merge install/codex/mcp.toml into project-local .codex/config.toml and run Codex from that trusted repo root. Full steps: install/codex/README.md.

Use either the native marketplace plugin or the manual TOML entry, not both. The manual path is the seat-key path for bots that must stay in one org (teamshared token mint scoped to that org) and the reliable way to skip the OAuth browser. Do not add a second TeamShared server next to the plugin. Bind the checkout with teamshared org bind <slug> either way; unbound /mcp keeps working.

Cursor desktop, Cursor Cloud, and Grok Bot still use Connect — do not add this tsk_ block to the plugin mcp.json.

License

MIT — see LICENSE.