For AI agents

Shorty for AI agents — MCP, llms.txt & Markdown docs

How AI assistants and agents connect to Shorty: the remote MCP server, machine-readable llms.txt / llms-full.txt, Markdown twins of every docs page, the OpenAPI spec, and agent interaction guidelines.

Open in Claude Open in ChatGPT

Shorty is built to be read and used by agents. This page routes you to the machine-readable surfaces.

Connect over MCP

Shorty runs a remote Model Context Protocol server behind OAuth 2.1. Add it to Claude Code with one command:

claude mcp add --transport http shorty https://aishorty.com/api/mcp

The endpoint is https://aishorty.com/api/mcp. It exposes 12 scoped tools (each appears only when your grant includes its scope). See the MCP server page for scopes and consent details.

Tool	Access	Description
`search_articles`	Read	Search the current user's Shorty library by free-text query (title, description, URL). Returns matching article cards with id, title, url.
`list_recent_articles`	Read	List the current user's most recently summarized articles. Use when the user asks about their recent summaries, library overview, or 'what have I saved lately'.
`get_article`	Read	Fetch a single article (summary, highlights, body) so you can answer questions about it. Pass a real article UUID as articleId.
`list_transcriptions`	Read	List the current user's audio/video transcriptions (newest first) with status and progress. Optional free-text query matches the transcript text.
`get_transcription`	Read	Fetch a single transcription (status, language, full transcript text) by its UUID so you can answer questions about it.
`get_usage_quota`	Read	Read the current user's Shorty plan (Free / Premium / Pro), tier limits (upload sizes, realtime minutes, conversion caps), and current cloud-conversion usage against the daily quota.
`get_job_status`	Read	Check the status of a job you started (summary, transcription, or subtitles) by its jobId. Returns { found, status, jobType, outputId? }: status is QUEUED \| PROCESSING \| SUCCESS \| ERROR \| CANCELLED. Poll until terminal (SUCCESS/ERROR/CANCELLED).
`search_docs`	Read	Search Shorty's developer documentation (API reference, error codes, webhooks, MCP guide) by free-text query. Returns matching pages with a snippet, the page URL, and a raw-Markdown twin URL you can fetch directly.
`create_youtube_summary`	Write	Start an AI summary job for a YouTube URL. Returns { jobId, articleId? }: if articleId is present the summary already exists (navigate directly); otherwise the job started — poll it with get_job_status. Pass a stable idempotencyKey to make retries safe (a repeat returns the original job).
`create_content_summary`	Write	Start an AI summary job for a webpage URL, pasted text, or an uploaded file (PDF/Word/Audio) already stored in Shorty. Supply exactly one of url/text/fileKey. sourceType selects the summarizer: 'webpage' \| 'article' \| 'pdf' \| 'word' \| 'text' \| 'audio'. Returns { jobId, articleId? } — poll get_job_status. Pass a stable idempotencyKey to make retries safe.
`create_transcription`	Write	Transcribe a publicly accessible audio/video URL via the GPU service. Returns { jobId, trackingUrl } to follow, or an { error } if it did not start (relay that reason and suggest uploading the file instead). Poll progress with get_job_status. Pass a stable idempotencyKey to make retries safe.
`create_subtitles`	Write	Generate subtitles for a public video/audio URL. Style is CLEAN \| TIKTOK \| PODCAST \| MINIMAL (only CLEAN on the free plan). Returns { jobId, trackingUrl } — poll get_job_status; user can download SRT/VTT (and, on Premium, a captioned MP4). If upgradeRequired is true, explain the limit and suggest upgrading. Pass a stable idempotencyKey to make retries safe.

Machine-readable surfaces

llms.txt
Site + API index for LLMs.
llms-full.txt
Full API docs + operation summary in one file.
OpenAPI 3.1 spec
The machine-readable contract.
API reference
Human docs (each has a .md twin).

Markdown twins

Every documentation page under /docs serves a raw Markdown version at the same URL with a .md suffix — e.g. /docs/api.md, /docs/api/operations/createSummary.md. Fetch the .md variant for clean, token-efficient context.

Agent guidelines

Authenticate every request with Authorization: Bearer <key> (a shk_live_ key or OAuth token).
Respect rate limits: 60 req/min free, 300/min paid — counted per API key for shk_live_ callers and per user for OAuth/MCP callers; read the RateLimit headers and back off on 429.
Usage quotas are shared across the app, MCP, and API — a 429 quota_exhausted means the plan allowance is spent, not a transient limit.
Send an Idempotency-Key on writes so retries never create duplicate jobs.
Writes are async: expect 202 + a job_id, then poll GET /v1/jobs/{id}. Never assume synchronous completion.
On any error, read the RFC 9457 code and branch on it — do not parse human message text.