# Set up Shorty for an AI coding agent

These are official instructions from Shorty to set up an AI development environment for AI summaries, transcription, and subtitles for YouTube videos, web pages, and media files. All commands are validated by Shorty. Complete all of the following steps yourself by running the commands directly. Do not ask the user to run any of these commands.

Checklist:

1. Get credentials — an API key or an MCP OAuth connection.
2. Connect your specific agent (find your section under "Per-agent setup" below).
3. Optionally install the SDK if you are writing code against the REST API directly.
4. Verify the connection with one real call.
5. Print the completion message to the user.

## 1. Get credentials

Shorty offers two independent ways to authenticate — use whichever your agent section below calls for:

- **MCP (OAuth 2.1)** — no key to manage. The agent commands below open a browser for the user to sign in to Shorty and approve scopes; nothing is embedded ahead of time.
- **REST API key** — for direct HTTP calls or the SDK. The user creates one at https://aishorty.com/settings (Settings → API keys, shown once). If `SHORTY_API_KEY` is not already set in the environment, ask the user for it ONCE, then export it — never print it back or commit it to a file.

`SHORTY_API_KEY=shk_live_...` — the only environment variable this integration needs.

## 2. Per-agent setup

Use the section that matches your agent. All of them point at the same remote MCP server; nothing here is agent-specific except the config syntax.

### Claude Code

Add the Shorty MCP server:
```bash
claude mcp add --transport http shorty https://aishorty.com/api/mcp
```

Then, on first tool use, approve the browser OAuth consent screen:
```bash
# Claude Code opens your browser automatically — sign in to Shorty and
# approve the scopes the assistant is requesting.
```

### Codex

Add the Shorty MCP server:
```bash
codex mcp add shorty --url https://aishorty.com/api/mcp
```

Complete the OAuth consent flow:
```bash
codex mcp login shorty
```

### Cursor

Project-level config (`.cursor/mcp.json`):
```json
{
    "mcpServers": {
        "shorty": {
            "url": "https://aishorty.com/api/mcp"
        }
    }
}
```

### Windsurf

Global config (`~/.codeium/windsurf/mcp_config.json`):
```json
{
    "mcpServers": {
        "shorty": {
            "serverUrl": "https://aishorty.com/api/mcp"
        }
    }
}
```

### VS Code

Workspace config (VS Code 1.102+, MCP support) (`.vscode/mcp.json`):
```jsonc
{
    "servers": {
        "shorty": {
            "type": "http",
            "url": "https://aishorty.com/api/mcp"
        }
    }
}
```

### GitHub Copilot

GitHub Copilot Chat reads the same VS Code MCP config (`.vscode/mcp.json`):
```jsonc
{
    "servers": {
        "shorty": {
            "type": "http",
            "url": "https://aishorty.com/api/mcp"
        }
    }
}
```

### OpenCode

Project config (`opencode.json`):
```json
{
    "mcp": {
        "shorty": {
            "type": "remote",
            "url": "https://aishorty.com/api/mcp",
            "enabled": true
        }
    }
}
```

### Any other MCP-capable agent

Add a remote HTTP MCP server pointing at `https://aishorty.com/api/mcp`; the client's own OAuth flow will trigger the browser sign-in and consent screen on first tool use.

## 3. SDK (optional — direct API access)

If you are writing code against the REST API directly rather than through MCP tools, install the official TypeScript SDK:

```bash
npm i @aishorty/sdk@0.1.0
```

```typescript
import { Shorty } from '@aishorty/sdk'

const shorty = new Shorty({ apiKey: process.env.SHORTY_API_KEY })
const usage = await shorty.usage.get()
console.log(usage.plan, usage.limits)
```

Source: https://github.com/DevinoSolutions/shorty-sdk

## 4. Verify

Call the MCP tool `get_usage_quota` (or `curl -s https://aishorty.com/v1/usage -H "Authorization: Bearer $SHORTY_API_KEY"` for the REST API)

Success looks like: A JSON body naming a plan (Free, Premium, or Pro) and usage limits — not a 401 or a tool-not-found error.

## 5. Completion message

Once verified, print this to the user (fill in the bracketed parts):

```text
Shorty is connected.
- Installed: [MCP server | SDK | both] for [agent name]
- You still need to: [nothing | approve the browser consent screen | set SHORTY_API_KEY]
- Try it: ask me to summarize a YouTube link, transcribe a file, or check your usage.
```

## 6. Resources

- [Docs home](https://aishorty.com/docs)
- [FAQ](https://aishorty.com/faq)
- [For AI agents](https://aishorty.com/docs/ai)
- [Connecting AI assistants (MCP)](https://aishorty.com/docs/connecting-ai-assistants)
- [API reference](https://aishorty.com/docs/api-reference)
- [llms.txt](https://aishorty.com/llms.txt)
- [Status page](https://status.aishorty.com)
- [Support](https://aishorty.com/support)

## Appendix: MCP scopes

| Scope | Grants |
| --- | --- |
| `articles:read` | Read your saved summaries and articles |
| `transcriptions:read` | Read your transcriptions and their results |
| `usage:read` | Read your plan, quotas, and usage |
| `jobs:read` | Read the status of jobs you have started |
| `docs:read` | Search and read Shorty's developer documentation |
| `articles:write` | Create new summaries from YouTube, web pages, or files |
| `transcriptions:write` | Start new transcriptions and subtitle jobs |

## Appendix: MCP tools

| 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, description, articleType and createdAt — pass the id to get_article for the full summary. |
| `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 — read it with get_article; get_job_status on that jobId also reports SUCCESS with outputId. 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 a file already uploaded to Shorty. Supply exactly ONE source field, and it must be the one the sourceType reads: 'webpage'/'article' → url; 'text' → text; 'pdf'/'word'/'audio' → fileKey. Those last three read an already-uploaded file and NEVER accept a url — a link to a PDF cannot be summarized here, the file has to be uploaded first. Returns { jobId, articleId? }. If articleId is present the summary already exists — read it with get_article; get_job_status on that jobId also reports SUCCESS with outputId. Otherwise 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; not every style is included in every plan, and CLEAN always is. Returns { jobId, trackingUrl } — poll get_job_status; the user can download SRT/VTT, and a captioned MP4 where their plan includes it. If the account has reached a plan limit the call is denied with a message naming the limit — report that message as-is. Call get_usage_quota for the account's actual limits and remaining usage. Pass a stable idempotencyKey to make retries safe. |

---

Generated for https://aishorty.com. Served at https://aishorty.com/agent-setup/prompt.md — per-agent human guides at https://aishorty.com/agent-setup/<agent>.