openhandle3.67 KB
View saved version →
---
name: openhandle
description: Use when the user asks for public Instagram, TikTok, X (Twitter), Reddit, or YouTube data (profiles, posts, comments, followers, search, trends, transcripts), or about their Openhandle account (balance, usage, spend, request history, failed requests, API keys). Covers tool choice, cost, freshness, paging, and errors for the openhandle MCP server.
---
# Openhandle
The `openhandle` MCP server gives you two groups of tools.
- **Platform tools** read public social data. Each name starts with the platform, for example `instagram_get_profile`, `tiktok_search_posts`, `twitter_list_followers`, `reddit_profile_get`, and `youtube_post_transcript_get`. Each tool is one REST endpoint with the same inputs and answers.
- **Account tools** read the user's own Openhandle workspace: `account_get_balance`, `account_get_usage`, `account_list_requests`, `account_get_request`, and `account_list_api_keys`. They are free and never touch social platforms.
If no Openhandle tools are visible, tell the user to connect Openhandle and approve in the browser. In Claude Code they run `/mcp` and pick `openhandle`. In ChatGPT they open the Openhandle plugin and connect it.
## Live data
- Platform tools return real public data. Each call uses the user's balance.
- Every result has `environment` in its metadata. If it is `test`, the answer is synthetic and real handles return not found. Tell the user, and tell them to connect again and pick Live.
## Inputs
- Profiles take `identifier` as `@username` or the raw platform ID. Posts take the native post ID, or the shortcode on Instagram. Never pass a URL. Take the handle or ID out of a URL first.
- `freshness` controls cache age: `live`, `24h` (default), `7d`, or `30d`. Older answers cost less and a `30d` cache hit is free. Use `live` only when the user needs data from this minute.
- List tools return a cursor. Pass it back as `cursor` for the next page. Fetch more pages only when the user needs them, because each page is one billed call.
## Answers
- `null` means the platform does not expose the value. It does not mean zero. Say "not available", never "0".
- YouTube lists show rounded counts and relative dates. When `metrics.isApproximate` is `true`, say "about". `createdAt` is exact; `approximateCreatedAt` is an estimated day. For exact numbers, read the single post with `youtube_post_get`.
- Error answers carry a stable `code`, such as `PROFILE_NOT_FOUND` or `PROFILE_PRIVATE`. Explain the code in plain words. These definitive answers are billed. Provider failures and internal errors are free.
- Result metadata has `requestId`, `actualCharge`, and `liveEquivalentPrice`. When the user asks what a call cost, read `actualCharge`.
## Account questions
- "How much credit do I have left?" → `account_get_balance`.
- "What did I spend this week?" or "Which endpoints do I use most?" → `account_get_usage` with `from` and `to` as `YYYY-MM-DD`. Set `groupBy` to `operation`, `platform`, `api_key`, or `source`.
- "Why did my requests fail?" → `account_list_requests` with `status` set to `client_error` or `server_error`, then `account_get_request` for one `requestId`.
- "Which keys are close to their cap?" → `account_list_api_keys`. Secrets are never returned.
If an account tool says the connection lacks the `read:account` scope, tell the user to disconnect Openhandle and connect again. If it says the user may not view the data, the user who approved the connection no longer has that access in the workspace.
## Limits
- The tools read public data only. They cannot post, follow, like, or read private accounts.
- The tools cannot top up the balance, create keys, or change settings. Send the user to https://app.openhandle.dev for that.
openhandle-quickstart10.4 KB
View saved version →
---
name: openhandle-quickstart
description: Integrate Openhandle public social data into an application's existing feature or a requested new feature. Use for provider replacement, reusable server client setup, Test verification, MCP connection, or moving an Openhandle integration from Test to Live.
---
# Add Openhandle Social Data
Connect Openhandle to the product behavior the user needs. Use Test first on that application path. Keep all credentials on the server.
## Before you start
1. Read the repository instructions.
2. Inspect the framework, package manager, server boundary, environment-variable pattern, and nearby request code.
3. Identify the requested platform, resource, and product behavior from the prompt and application.
4. Locate existing provider calls and the feature that consumes their data.
5. Check https://openhandle.dev/docs/api-reference for support of the requested platform and operation before implementing them. Explain unsupported requests without inventing an endpoint or substituting another platform.
Choose the scope from the user's request:
- **Replace a provider:** Replace the selected feature's data access. Preserve its existing behavior and application contract. Map Openhandle fields, pagination, and errors to that contract. Report capability gaps before replacing behavior that depends on them.
- **Add a feature:** Connect the requested data to the product's route, action, job, or interface using existing patterns.
- **Configure the client:** Set up reusable server configuration when the user asks only for configuration.
- **Unspecified setup:** Configure the reusable server client first. Ask one focused question about the intended feature before adding product behavior or replacing a provider. Continue independent setup while awaiting the answer.
Use an explicit request and clear application context without asking the user to repeat them. A generic setup request does not select a provider to replace. Do not invent a lookup page, demo route, or test endpoint to make setup appear complete. A successful sample request proves connectivity, not product integration.
## Get a Test credential
Check whether `OPENHANDLE_TEST_KEY` is available to the application runtime without displaying its value or reading secret files. Use the project's existing secret configuration if it uses another variable name.
A missing shell variable does not prove that the application lacks a key. Inspect configuration references and use a presence-only check inside the existing application container or runtime when accessible. Do not dump environment variables. If deployment credentials are inaccessible, report availability as unverified.
If it is unavailable, ask the user to:
1. Create a free account at https://app.openhandle.dev/signup (100 free requests, no card needed), or sign in at https://app.openhandle.dev/signin.
2. Open **API Keys**.
3. Create a **Test** key.
4. Store it as `OPENHANDLE_TEST_KEY`, or the existing configured variable, through the project's normal secret workflow.
5. Confirm when the variable is available.
Never ask the user to paste an API key into chat. Never write a real secret into source control, examples, logs, browser code, mobile code, or test fixtures. Add only a placeholder to an example environment file when the project uses one.
Test keys start with `oh_test_`. They only access deterministic synthetic data. Test requests have a `$0.000` actual charge.
Do not invent a working key or treat a placeholder as a credential. SDK installation does not create a key. Report key creation only when confirmed by the service.
While credentials are pending, complete the authorized implementation and mocked tests using documented fixtures. Do not replace missing credentials with a synthetic success in application code. Stop before authenticated verification and report real Test verification as incomplete. State the remaining credential action and how to run verification after configuration.
#
Preview of the first 4,000 characters. Read full instructions →
