Teams via MCP - xysq documentation

Once your agent is connected to xysq via MCP, it can work with team vaults as naturally as personal ones. You decide which teams are in scope from the xysq web UI — your agent picks it up automatically on the next call.

How team scope works

Every team membership has an MCP sync toggle on its card at app.xysq.ai/teams. The toggle is your standing scope:

Toggled on → every memory your agent writes via MCP fan-writes to your personal vault and this team’s vault. Every recall reads from both.
Toggled off → MCP doesn’t see this team at all. You can still browse the team’s vault in the web UI.

Toggling on or off takes effect on the next MCP tool call — no reconnect, no restart, no config edit. The backend reads toggle state from the database on every request. This applies to OAuth-authorised MCP sessions (sessions where you signed in via the web flow — the path the Claude Code plugin uses by default). If you connect via an xysq_* API key (SDK, server-to-server, automation), declare team scope per request with the X-Xysq-Teams header — see the Claude Code API-key alternative for the wiring.

Before you start

You’ll need:

xysq connected via MCP (Claude Code recommended, or Claude Desktop, Cursor, etc.)
A team created in app.xysq.ai with at least one member
MCP sync toggled on for that team at app.xysq.ai/teams

That’s it. Your agent inherits the scope. You don’t need to memorise or paste a team ID.

Telling your agent which team to use

In most cases, you don’t have to — once a team is toggled on, your agent reads and writes that team’s vault by default alongside your personal one. If you want a single call to go to ONE team only (and not broadcast to all your toggled teams), name the team in your prompt:

Retain this to the Acme Engineering team vault only: We've decided to use Postgres, not MySQL.

Your agent will pass team_id="<acme-id>" on that call. See Per-call overrides below for the full set of narrowing options. If you need the team’s UUID, ask:

List my xysq teams.

Your agent calls list_teams() and shows every team you belong to, with its ID, your role, and whether MCP sync is currently on.

Retaining to a team vault

Explicit retain

Retain this to the Acme Engineering team vault: We've decided to use Postgres, not MySQL. Final decision.

Save to team memory: the API rate limit for production is 1000 req/min, agreed with infra on the 14th.

During a conversation

Once you’ve told your agent to use a team vault, it retains context there automatically — the same way it would for your personal vault:

We're going with the monorepo structure. Two packages: api and web. Infra will mirror this.

Got it — retaining that decision to the team vault.

Retaining a decision with context

Retain to team: decision — we're deprecating the v1 API by end of Q2. Owner: backend team. Ticket: ENG-441.

Good team memories include who decided, what was decided, and when. Your agent can infer most of this from context if you provide it naturally.

Recalling from a team vault

At session start

Ask your agent to load team context at the beginning of a session — this is the most efficient pattern:

Before we start, recall what the team has decided about the payment integration.

Load the Acme Engineering team context so you're up to speed.

Your agent will call memory_reflect("team context and recent decisions", team_id="<id>") and synthesise the relevant facts into a working summary.

Targeted recall

What has the team decided about authentication?

What do we know about the deployment process for the web package?

Has anyone captured notes from the Q1 retro?

Cross-checking personal and team context

Your agent has access to both vaults simultaneously. You can ask questions that span both:

What's my personal preference on code reviews, and what has the team agreed on?

xysq routes personal recall to your vault and team recall to the team vault — you get a unified answer.

Reflecting on team knowledge

memory_reflect synthesises a grounded answer from stored memories. It works identically for team vaults:

What should I know about this team's approach to API design before starting this ticket?

Summarise what the team has agreed on so far about the new onboarding flow.

What are the outstanding decisions the team still needs to make on the data model?

Your agent calls reflect behind the scenes and returns a direct answer — no need to browse raw memories yourself.

Working with multiple teams

Every team with MCP sync toggled on is in scope by default — your agent writes to all of them and reads from all of them. No “active team” to track. To direct a single call to a specific team (instead of broadcasting), name it:

Retain to the Design Systems team only: our token naming convention is documented in Figma, link in the team wiki.

What has the Platform team decided about deployment?

Your agent passes team_id="<id>" on that call. The other toggled teams are excluded for that call only — your standing scope doesn’t change. To stop syncing a team entirely, flip its toggle off at app.xysq.ai/teams — your agent stops seeing it on the very next call.

Deleting a team memory

Members with admin or owner role can delete memories from the team vault:

Delete the team memory about the v1 API deprecation — that decision was reversed.

Remove the outdated deployment notes from the team vault.

MCP tools reference

These are the underlying tools your agent uses when you ask it to work with team vaults. You don’t need to call them directly — your agent handles this — but understanding them helps you write more precise instructions.

Tool	What it does	Minimum role
`list_teams()`	Lists all teams you belong to with IDs and roles	member
`memory_list(team_id=...)`	Lists recent memories from the team vault	ro
`memory_recall(query, team_id=...)`	Semantic search over team memories	ro
`memory_reflect(query, team_id=...)`	Synthesised answer from team memories	ro
`memory_retain(content, team_id=...)`	Stores a memory in the team vault	rw
`memory_delete(memory_id, team_id=...)`	Deletes a memory from the team vault	admin

Tips for effective team memory

Retain decisions, not discussions. A 30-message thread about auth design is noise. The final decision — what was agreed, who owns it, what it replaces — is signal. Retain the outcome. Include ownership and dates. “We’ll use JWTs” is harder to reason about than “Auth decision (14 April): JWTs with 1-hour expiry. Owner: backend. Replaces the session cookie approach.” Use the team vault for shared facts, personal vault for personal preferences. Your coding style preferences belong in your personal vault. The team’s API versioning policy belongs in the team vault. Recall at session start, not mid-conversation. Loading team context at the start of a session is cheaper and more coherent than piecemeal lookups mid-task. Correct outdated memories. Decisions change. When something is reversed or superseded, delete the old memory and retain the new one. Stale context is worse than no context.

MCP sync toggle reference

The mechanics are covered in How team scope works above — this section is a quick reference for the edge cases.

Default state. New teams are toggled off. You opt in deliberately, per team.
At invite time. The accept-invitation screen shows the same toggle inline, so you can choose whether MCP sync is on the moment you join.
Limit. Up to 10 teams can be toggled on at once. The UI prevents an 11th; toggle one off first.
Roles. The toggle works for every membership role (owner / admin / rw / ro). Read-only members who toggle on will see team memories in recall; their writes are still blocked by the role check.
Scope, not access. Toggling off only removes the team from MCP scope — you can still browse its vault in the web UI normally.
API-key sessions are not affected. The toggle controls OAuth-authorised MCP sessions only. API-key callers declare scope per request via the X-Xysq-Teams header.

Per-call overrides

The MCP sync toggle sets your standing scope — which teams your agent reaches by default. For a single tool call you can narrow further, without touching the toggle. Every memory tool (memory_retain, memory_recall, memory_list, memory_delete) accepts the same three optional arguments:

Argument	Effect
`team_id="<id>"`	This call goes to your personal vault + that one team only. Other toggled teams are excluded.
`team_ids=["<a>","<b>"]`	This call goes to personal + those teams only. A subset of your toggled set.
`personal_only=true`	This call goes to your personal vault only. No teams.

If you pass nothing, the call broadcasts to your full scope: personal + every team currently toggled on.

Constraints

Out-of-scope teams are rejected. Any team_id or member of team_ids you pass must be a team you’ve toggled MCP sync ON for. Passing one that isn’t returns forbidden — there’s no silent fallback. This prevents accidentally leaking memories into a team you didn’t mean to share with.
Don’t mix personal_only=true with team_id / team_ids. They contradict each other; the call is rejected with invalid_args.
Don’t pass both team_id and team_ids. Pick one.

Tag shortcut

Tagging a memory with private is equivalent to personal_only=true for memory_retain — useful when the tag is already part of how you classify the memory:

memory_retain(content="...", tags=["private", "..."])

This is the only tag with this routing effect. Other tags don’t change scope.

Examples

# Default — broadcast to personal + every toggled team
memory_retain(content="Decision: ship v2 on Tuesday")

# Narrow this one call to just team alpha (+ personal)
memory_retain(
  content="Action item: Alex owns the migration",
  team_id="<alpha-id>",
)

# Narrow to a subset (personal + alpha + gamma; beta excluded)
memory_retain(
  content="Cross-team sync notes",
  team_ids=["<alpha-id>", "<gamma-id>"],
)

# Force personal-only for a sensitive note
memory_retain(
  content="Salary conversation context",
  personal_only=True,
)

# Same effect via tag
memory_retain(
  content="1:1 prep notes",
  tags=["private", "1on1"],
)

How this composes with the MCP sync toggle

Toggle is your umbrella — the maximum set of teams a call can reach.
Overrides narrow within the umbrella — they can subtract teams, never add.
To send a memory to a team that isn’t toggled on, flip the toggle first. The UI is the only way to expand scope.

This keeps the consent model clear: opt-in is a deliberate UI action; per-call narrowing is for everyday flexibility.

​How team scope works

​Before you start

​Telling your agent which team to use

​Retaining to a team vault

​Explicit retain

​During a conversation

​Retaining a decision with context

​Recalling from a team vault

​At session start

​Targeted recall

​Cross-checking personal and team context

​Reflecting on team knowledge

​Working with multiple teams

​Deleting a team memory

​MCP tools reference

​Tips for effective team memory

​MCP sync toggle reference

​Per-call overrides

​Constraints

​Tag shortcut

​Examples

​How this composes with the MCP sync toggle