Developer docs
MCP
Agents get the same governed access as the REST API: they can read and draft freely within scope, and every write waits for a person to approve the exact payload.
Connect
Endpoint: https://yousaid.dev/mcp (MCP over HTTP, protocol 2025-06-18)
Header: Authorization: Bearer ysmcp_...- Workspace owners and admins create an MCP connection per product. read_draft grants mcp:read and mcp:draft; full also grants mcp:write. Connections expire after 1 to 365 days (default 180), at most 20 are active per product, and the token is shown once.
- The product and tenant come from the credential. A tool can never reach another product.
- A connection belongs to the environment it was created in (production or staging), like a service API key. Presented to another environment it answers 403 ENVIRONMENT_SCOPE_MISMATCH.
- Each credential may make 120 requests per minute; over that the server answers 429 with retry-after: 60.
- Canonical tool names start with yousaid.; unprefixed aliases are kept for older clients.
Action levels
| Level | Scope | What happens |
|---|---|---|
| read | mcp:read | Runs immediately. Returns data the credential may see. |
| draft | mcp:draft | Runs immediately and produces a non-binding draft or a queued request. Nothing is sent or published. |
| write, propose, decide | mcp:write | Needs a person to approve this exact payload first. |
Some actions are never available to agents at any level: approving or rejecting proof, managing consent, revoking directly, publishing paid use, exporting raw originals and configuring agents. proof_approve exists only to explain that; it is always refused.
Approval flow
- The agent calls a write tool without approvalId. YouSaid runs the tool's policy checks first. If any fails (for example request fatigue, an open support issue, an incentive tied to sentiment or anything that would gate reviews), the answer is POLICY_CHECK_FAILED and no approval is requested.
- Otherwise the answer is an approval envelope: status approval_required, approvalId (mcpa_...), approvalUrl, expiresAt (24 hours), the policy checks, and the audience count for bulk actions.
- A workspace member opens the approval URL and approves or rejects the exact payload.
- The agent repeats the identical call with approvalId. A changed payload, a reused approval or an expired one answers APPROVAL_INVALID. Each approval runs once.
{
"status": "approval_required",
"approvalId": "mcpa_...",
"approvalUrl": "https://yousaid.dev/app?mcp_action=mcpa_...",
"expiresAt": "2026-09-23T10:00:00.000Z",
"requiresApproval": true,
"policyChecks": [{ "name": "fatigue", "status": "pass" }, { "name": "no_review_gating", "status": "pass" }]
}Every tool call is written to the workspace audit log with the tool, outcome, duration and a digest of the result.
Tools
The live list is what the server returns from tools/list. The table below is checked against the server code by an automated test. The static manifest at /.well-known/sansa-mcp.json currently lists the Customer Loop and Room tools only.
| Tool | Level | Approval | Summary |
|---|---|---|---|
yousaid.get_product_context | read | No | Feedback totals, open loops, ideas, surveys and updates for the credential's product. |
yousaid.search_customer_evidence | read | No | Search recent customer signals; returns original words and stable IDs for citation. |
yousaid.get_customer_thread | read | No | One complete customer conversation in the credential's product. |
yousaid.search_source_records | read | No | Search attributed source records; evidenceClassification is required. |
yousaid.get_source_record | read | No | One attributed source record. |
yousaid.create_source_record | write | Human | Create an immutable attributed source record after a teammate approves the exact payload. |
yousaid.draft_customer_reply | draft | No | Non-binding reply draft grounded in a thread's evidence. Flagged needsHumanReview when the model is not yet evaluated. |
yousaid.draft_product_update | draft | No | Non-binding product update draft citing signal IDs. Flagged needsHumanReview when the model is not yet evaluated. |
yousaid.create_idea | write | Human | Create a feature idea after human approval. |
yousaid.create_product_update | write | Human | Create a product update after human approval. |
yousaid.list_rooms | read | No | Rooms in the credential's product. |
yousaid.get_room | read | No | One Room with its customer-visible state. |
yousaid.search_rooms | read | No | Search Room messages and canonical answers. |
yousaid.post_room_message | write | Human | Post a Room message after human approval. |
yousaid.get_room_safety_status | read | No | Moderation and safety state for a Room. |
yousaid.create_room_poll | write | Human | Create a Room poll after human approval. |
yousaid.create_room | write | Human | Open a Room after human approval. |
yousaid.get_room_canvas | read | No | Read a Room Canvas. |
yousaid.update_room_canvas | write | Human | Update a Room Canvas after human approval. |
yousaid.compile_room | draft | No | Compile a Room into a cited draft. |
yousaid.invite_room_cohort | propose | Human | Propose a cohort invitation; a human decides. |
yousaid.search_knowledge | read | No | Search published Room knowledge. |
yousaid.generate_prd | draft | No | Draft a PRD from a Room. An AI summary is flagged needsHumanReview when the model is not yet evaluated. |
yousaid.list_room_approvals | read | No | Pending and decided Room approvals. |
yousaid.decide_room_approval | decide | Human | Relay a human's approval decision; the tool never decides on its own. |
yousaid.proof_search | read | No | Search approved proof with per-channel eligibility and source policy. |
yousaid.proof_get | read | No | One proof item. |
yousaid.proof_consent_status | read | No | Consent state, scope and receipt. Agents cannot change consent. |
yousaid.proof_claims_check | read | No | Claims in the approved version with their verification state and evidence counts. |
yousaid.proof_opportunities_list | read | No | Ask candidates by state. |
yousaid.proof_brand_mentions_list | read | No | Brand Monitor mentions by state. |
yousaid.proof_placement_recommend | read | No | Which active placements an item is eligible for, with reasons. |
yousaid.proof_placement_preview | read | No | Items in a placement with their live eligibility. |
yousaid.proof_export_create | read | No | Export approved proof (approved words only, no raw originals). |
yousaid.proof_item_summarize | draft | No | AI summary of an item. |
yousaid.proof_request_draft | draft | No | AI-drafted ask message. Never sends. |
yousaid.proof_case_study_compile | draft | No | Source-cited case study draft; uncited statements and invented numbers are rejected. |
yousaid.proof_asset_generate_draft | draft | No | Quote card draft from an approved version. |
yousaid.proof_request_approval | draft | No | Queue an item version for human review. |
yousaid.proof_revocation_request | draft | No | File a revocation request; a human with consent authority completes it. |
yousaid.proof_approve | read | No | Always refused for agents. Approving publication is a human decision. |
yousaid.proof_request_schedule | write | Human | Create proof requests for up to 200 recipients. Fatigue, open-support, incentive and review-gating checks must pass before approval is even requested. |
yousaid.proof_placement_add | write | Human | Add an approved item to a placement when consent and eligibility pass. |
yousaid.proof_placement_publish | write | Human | Publish a placement; ineligible items are listed in the approval envelope and excluded. |
yousaid.proof_health_list | read | No | Deterministic Proof Health scores. |
yousaid.proof_gaps_analyze | read | No | Coverage gaps by dimension. |
yousaid.proof_room_create | write | Human | Open a private Proof Room for a story; refused when the customer withdrew or asked to withdraw. |
Resources and prompts
| Resource | Contents |
|---|---|
| yousaid://capabilities | What this server and credential can do. |
| yousaid://product/context | The connected product. |
| yousaid://sources/schema | The attributed source record schema. |
| yousaid://proof/policies | Source policies, agent action levels and the human-only actions. |
| yousaid://proof/brand-kit | Default quote-card theme tokens and formats. |
| yousaid://proof/taxonomy | Item types and statuses, channels, placement types, consent states and ledger event names. |
| yousaid://proof/approved | Up to 50 approved proof items with their approved words. |
| yousaid://proof/health | Proof Health summary and top gaps. |
| yousaid://proof/placements | Placements in the product. |
| yousaid://proof/analytics-definitions | How proof metrics are defined and labeled. |
Prompts: yousaid.grounded_customer_reply, yousaid.evidence_backed_update and yousaid.source_backed_attribution. Each tells the model to cite only returned ids and not to send or publish anything on its own.