YAAD
Agent MCP docs
Client activity ↗
Browse this guide
ConnectWorkflowToolsExamplesSecurityTroubleshooting
Human-reviewed by design

Let agents research.Keep the final say.

YAAD Agent MCP lets Cursor, Claude Code, ChatGPT, and compatible clients read your application workspace and submit cited create, update, or delete proposals. Nothing changes until you approve it inside YAAD.

Request pathPOST /mcp
1

Research

The client searches the web and gathers public sources.

2

Propose

YAAD validates evidence and stores a pending proposal.

3

Review

You compare the field diff, sources, and warnings.

4

Apply

Approval rechecks ownership and version atomically.

02
Connection

Connect your client

Use the exact HTTPS endpoint below. The client discovers Clerk OAuth, opens your browser, and asks you to sign in and consent. Use the same YAAD account that owns the applications you want the agent to access.

https://yaad.adnantariq.pk/mcpHTTPS · OAuth · POST
Cursor

Remote MCP configuration

Add this entry to your Cursor MCP configuration, then enable the server.

json
{
  "mcpServers": {
    "yaad": {
      "url": "https://yaad.adnantariq.pk/mcp"
    }
  }
}
Claude Code

One command, then OAuth

Run the command, open /mcp, select YAAD, and authenticate.

bash
claude mcp add --transport http yaad https://yaad.adnantariq.pk/mcp
ChatGPT

Custom app / developer mode

Add the remote endpoint from ChatGPT's custom app flow and let it scan the tools. Full MCP write support is currently documented for Business and Enterprise/Edu; Pro supports read/fetch custom MCP use. Availability can change.

OpenAI's current MCP availability ↗
Any MCP client

Protocol requirements

Use Streamable HTTP with OAuth discovery and dynamic client registration. YAAD is stateless: it does not expose SSE or require Redis-backed sessions.

GET /.well-known/oauth-protected-resource/mcpGET /.well-known/oauth-authorization-serverPOST /mcp
03
Operating model

The safe research loop

A

Inspect

Read the schema and existing applications before researching.

B

Research

Prefer official program and institution pages; keep public URLs.

C

Validate

Run the validation tool and correct evidence or duplicate warnings.

D

Propose

Submit one idempotent proposal, then send the user to YAAD review.

04
Interface

Nine focused tools

yaad_get_application_schema

Read fields, enums, and safety rules before composing data.

yaad_list_applications

Page through the signed-in user's application summaries.

yaad_get_application

Read one application and sanitized document metadata.

yaad_validate_application_proposal

Check evidence, URLs, duplicates, versions, and document rules without storing.

yaad_propose_application_create

Place a researched application into the human-review queue.

yaad_propose_application_update

Propose a version-bound field patch for an existing application.

yaad_propose_application_delete

Request a cascade delete; YAAD still requires two confirmations.

yaad_list_application_proposals

Read pending or historical proposals with cursor pagination.

yaad_get_application_proposal

Inspect one proposal, its evidence, warnings, client, and decision state.

List tools use cursor pagination with a default of 20 and a maximum of 50. Proposal responses include the proposal ID, status, review URL, warnings, and whether the result was an idempotent replay.

05
Patterns

Three practical calls

EXAMPLE 01

Read before you research

Ask for the schema, then list applications so the agent can avoid duplicate work.

json
Tool: yaad_list_applications

{
  "limit": 20,
  "status": "applying",
  "query": "Cambridge"
}
EXAMPLE 02

Validate cited findings

Validate the complete proposal before storing it. Every researched field points to an official source ID.

json
Tool: yaad_validate_application_proposal

{
  "action": "create",
  "payload": {
    "scholarshipName": "Example Global Scholarship",
    "applicationType": "Scholarship",
    "institution": "Example University",
    "country": "United Kingdom",
    "degreeLevel": "Master's",
    "funding": "Full tuition and living stipend",
    "status": "saved",
    "deadline": 1798761599000
  },
  "sources": [
    {
      "id": "official-program",
      "url": "https://example.edu/scholarships/global",
      "title": "Official scholarship page",
      "accessedAt": 1786316400000,
      "kind": "official"
    }
  ],
  "fieldEvidence": [
    { "field": "scholarshipName", "sourceIds": ["official-program"] },
    { "field": "institution", "sourceIds": ["official-program"] },
    { "field": "country", "sourceIds": ["official-program"] },
    { "field": "degreeLevel", "sourceIds": ["official-program"] },
    { "field": "funding", "sourceIds": ["official-program"] },
    { "field": "deadline", "sourceIds": ["official-program"] }
  ]
}
EXAMPLE 03

Submit an idempotent proposal

Use a stable key for the logical operation. Retrying the same request returns the original proposal.

json
Tool: yaad_propose_application_create

{
  "payload": {
    "scholarshipName": "Example Global Scholarship",
    "applicationType": "Scholarship",
    "institution": "Example University",
    "country": "United Kingdom",
    "degreeLevel": "Master's",
    "funding": "Full tuition and living stipend",
    "status": "saved",
    "deadline": 1798761599000
  },
  "sources": [
    {
      "id": "official-program",
      "url": "https://example.edu/scholarships/global",
      "title": "Official scholarship page",
      "accessedAt": 1786316400000,
      "kind": "official"
    }
  ],
  "fieldEvidence": [
    { "field": "scholarshipName", "sourceIds": ["official-program"] },
    { "field": "institution", "sourceIds": ["official-program"] },
    { "field": "country", "sourceIds": ["official-program"] },
    { "field": "degreeLevel", "sourceIds": ["official-program"] },
    { "field": "funding", "sourceIds": ["official-program"] },
    { "field": "deadline", "sourceIds": ["official-program"] }
  ],
  "reason": "Add a researched scholarship for human review.",
  "idempotencyKey": "example-global-scholarship-2027-v1"
}
EXAMPLE 04

Update against a known version

Read updatedAt first. YAAD marks the proposal conflicted if the application changes before approval.

json
Tool: yaad_propose_application_update

{
  "applicationId": "<application-id>",
  "baseUpdatedAt": 1786316400000,
  "patch": {
    "deadline": 1799366399000,
    "funding": "Full tuition, travel, and monthly stipend"
  },
  "sources": [
    {
      "id": "official-update",
      "url": "https://example.edu/scholarships/global/dates",
      "title": "Official dates and funding",
      "accessedAt": 1786402800000,
      "kind": "official"
    }
  ],
  "fieldEvidence": [
    { "field": "deadline", "sourceIds": ["official-update"] },
    { "field": "funding", "sourceIds": ["official-update"] }
  ],
  "reason": "Refresh the deadline and funding from the official notice.",
  "idempotencyKey": "example-global-update-2027-v1"
}
06
Trust boundary

Evidence and privacy

Evidence required

  • ✓Every changed researched field needs at least one source classified by the agent as official.
  • ✓Secondary sources may supplement official evidence, but cannot replace it.
  • ✓YAAD shows the classification and hostname for human verification; it does not scrape submitted pages.

URLs constrained

  • ✓Only public HTTP and HTTPS URLs are accepted.
  • ✓Credentials embedded in URLs are rejected.
  • ✓Localhost, loopback, link-local, and private-network targets are rejected.

Documents sanitized

  • ✓Agents see filename, document type, content type, upload time, and checklist linkage only.
  • ✓Cloudinary identifiers, secure URLs, notes, and file contents are never exposed.
  • ✓Agents cannot upload, move, delete, or attach a document from another application.

Sensitive values expire

  • ✓Never send passwords, API keys, tokens, recovery codes, or other credentials.
  • ✓Pending proposals may temporarily retain portal username, application number, and portal notes.
  • ✓Approval, rejection, or conflict replaces those retained values with SHA-256 redaction markers.
07
Guardrails

Limits and standard errors

120
reads / minute
60
new proposals / hour
200
pending proposals
AUTH_REQUIRED

Reconnect and complete Clerk login and consent.

VALIDATION_ERROR

Correct the cited fields, URL, payload, or document linkage.

NOT_FOUND

The owned application or proposal does not exist.

FORBIDDEN

The operation crosses an ownership or document boundary.

CONFLICT

The target changed after the agent read its updatedAt value.

RATE_LIMITED

Wait for the read/proposal window or review pending proposals.

BRIDGE_UNAVAILABLE

The secure Vercel-to-Convex bridge could not complete the request.

08
Diagnostics

When a client will not connect

The browser login succeeds, then redirect_uri is rejected+

Remove the stale client registration and reconnect so Dynamic Client Registration stores the client's current loopback callback. For MCP Inspector, use a fresh callback port and relogin.

ChatGPT says “Unsafe URL”+

Enter the exact public HTTPS endpoint—https://yaad.adnantariq.pk/mcp—in the custom app flow. Confirm your plan/workspace has developer mode access and let ChatGPT scan the tools. If the message remains before OAuth or any server request appears, it is a ChatGPT URL-safety decision rather than a YAAD validation error; the same endpoint can still be used with Cursor and Claude Code.

The client disappears or asks you to authenticate again+

Reconnect and complete Clerk consent. OAuth clients should requestopenid profile email; clients that need renewal may also request offline_access when advertised by the provider.

A proposal is conflicted+

The application changed after the agent read it. Fetch the current application again, reconstruct the patch against its newupdatedAt, validate, and submit a new idempotency key.