# Vyuh Drift MCP Server — Agent Guide

This file provides autonomous AI agents (Claude, Cursor, custom LangChain/CrewAI agents) with complete operational instructions for interacting with the Vyuh Drift Model Context Protocol (MCP) server.

## Connection Details
- **Endpoint**: `https://drift.vyuhmatrix.com/api/mcp`
- **Protocol**: `JSON-RPC 2.0` over HTTP POST
- **Protocol Version**: `2025-06-18`
- **OAuth Discovery**: `https://drift.vyuhmatrix.com/.well-known/oauth-protected-resource`

## Recommended Workflow for AI Agents
1. **Always call `list_channels` first**:
   Inspect available social channels, their health status, and whether their autopublish policy is `AUTO` or `APPROVAL`.
2. **Publish or stage posts with `publish`**:
   Submit your post with `content` and target `channels`.
   - If a channel has `APPROVAL` policy, the post will be staged and you will receive an `approvalUrl`.
   - Never promise your user that a post is live immediately.
3. **Verify with `check_post`**:
   After the `checkAfter` timestamp, call `check_post` with the returned `ref` or `postId`.
   - Report `VERIFIED` only when `check_post` confirms it.
   - If `MISSING`, alert the human that platform moderation or rate limits prevented publishing.

## Tools Reference
### `list_channels`
Lists every connected channel together with its credential health, its autopublish policy (whether an agent may publish here without a human, or the post will be staged for approval instead), and whether posts on it are verifiable (whether a later check_post call can prove the post is really live on the platform, or only confirm that it was sent). Call this before publish so you know in advance which of the requested channels will go out immediately and which will wait on a person.

- **Required Parameters**: none
- **Properties**:
  - None
- **Safety**: ReadOnly = `true`, Destructive = `false`

### `channel_rules`
Provides platform limits, character lengths, thread support, and required fields before drafting content. Call this to know exact character limits and supported features for each platform before composing posts.

- **Required Parameters**: none
- **Properties**:
  - `provider` (string): Optional provider id (e.g. "x", "linkedin", "bluesky"). Omit to list rules for all platforms.
- **Safety**: ReadOnly = `true`, Destructive = `false`

### `get_post_metrics`
Fetches real, unpadded platform engagement metrics (likes, reposts, comments, impressions) for a post. Never invents figures or estimates rates without a real denominator; reports null where unexposed by the platform.

- **Required Parameters**: ref
- **Properties**:
  - `ref` (string): Full post id, or its 4-character short id.
- **Safety**: ReadOnly = `true`, Destructive = `false`

### `check_post`
Reports what the PLATFORM says about a post, not what this app recorded when it was sent — catching the gap between the two is the whole point of this tool. VERIFIED means the post was fetched back from the platform and is really there. MISSING means the platform accepted the post but it is not there now (removed, rejected after the fact, or never actually landed). UNVERIFIABLE means we could not check and are not guessing either way. A null verification means the post has not been checked yet and must NEVER be read as success. Accepts either the full post id or its 4-character short id from a previous publish or list_pending_approvals call.

- **Required Parameters**: ref
- **Properties**:
  - `ref` (string): Full post id, or its 4-character short id.
- **Safety**: ReadOnly = `true`, Destructive = `false`

### `publish`
Publishes or schedules a post across one or more channels. Channels whose autopublish policy is APPROVAL (see list_channels) are staged for a human to release rather than published — the result gives a per-channel disposition (publishing, scheduled, awaiting_approval, or skipped_unhealthy) so you know exactly what happened to every channel you asked for. checkAfter is the timestamp after which check_post can actually confirm the post is live — do not assume success before then, and do not assume success even after unless check_post says VERIFIED. A request that mixes automatic and approval channels creates TWO separate posts, and approvalPostId identifies the gated one (distinct from the primary postId returned).

- **Required Parameters**: content, channels
- **Properties**:
  - `content` (string): The text content of the post.
  - `channels` (array): Channel ids or "provider:handle" strings from list_channels. At least one is required.
  - `scheduledAt` (string): ISO 8601 timestamp to schedule for later. Omit to publish now.
  - `threadParts` (array): Additional parts of a thread or split post, in order after content.
  - `media` (array): Media URLs or references to attach to the post.
  - `force` (boolean): Optional. Set to true to bypass the deterministic anti-fluff quality gate.
- **Safety**: ReadOnly = `false`, Destructive = `true`

### `list_pending_approvals`
Lists posts that are staged on an APPROVAL channel and blocked on a human before they can go out. Each entry includes an approvalUrl — the page where a person reviews and releases it. Use this to see what is waiting and report it to a human, not to release it yourself: there is no tool in this server that approves a post. The result is one PAGE of the queue: `total` is how many are waiting in all, `count` is how many are in this page, and `hasMore`/`nextOffset` tell you whether to call again. Report `total` to the human, never `count`.

- **Required Parameters**: none
- **Properties**:
  - `limit` (integer): How many to return in this page. Defaults to 25.
  - `offset` (integer): How many to skip. Pass the nextOffset from the previous result to page on.
- **Safety**: ReadOnly = `true`, Destructive = `false`

### `recon_domain`
Universal Domain Context Profiler. Extracts a target website or competitor domain's vertical, tech stack, ICP buyer personas, key pain points, and positioning angles directly from the live DOM.

- **Required Parameters**: url
- **Properties**:
  - `url` (string): The target domain or website URL (e.g. "https://linear.app" or "notion.so").
- **Safety**: ReadOnly = `true`, Destructive = `false`

### `scan_outliers`
Vertical Outlier Radar. Scans public discussions, news, and social feeds for mathematical anomalies and breakout viral posts (3x-10x median lift) with hook patterns, buyer objections, and market gaps.

- **Required Parameters**: query
- **Properties**:
  - `query` (string): The topic, keyword, or vertical to analyze (e.g. "developer tools", "ai agents", "crm").
  - `domainUrl` (string): Optional URL to provide domain context calibration.
- **Safety**: ReadOnly = `true`, Destructive = `false`

### `export_sales_outreach`
Cold Outbound Sequence Exporter. Mines competitor friction points and outputs a battle-tested 3-touch outreach sequence (Day 1 problem, Day 4 architecture, Day 8 offer) with Apollo/Instantly-compliant CSV.

- **Required Parameters**: competitorUrl
- **Properties**:
  - `competitorUrl` (string): The competitor website URL to mine friction points against.
- **Safety**: ReadOnly = `true`, Destructive = `false`


## Error Handling
Tool errors return JSON-RPC 200 with `result.isError = true` and plain-language explanation in `result.content[0].text`. Read the error message and adjust your parameters.