# Social data for your agent. One server, every endpoint a tool.

Openhandle gives your agent access to Instagram, TikTok, and X. Each API endpoint becomes one tool.

Server URL: https://api.openhandle.dev/mcp (Streamable HTTP)

## Connect

### Claude

```text
https://api.openhandle.dev/mcp
```

1. **Add a custom connector.** Open Settings, then Connectors, then Add custom connector. Paste the server URL.
2. **Approve in the browser.** Openhandle opens in a tab and asks you to approve the connection. Pick Test or Live on that screen.
3. **Ask for social data.** The tools show up in the chat. Ask in plain words and the agent picks the right one.

### ChatGPT

```text
https://api.openhandle.dev/mcp
```

1. **Add a connector.** Open Settings, then Connectors, then Create. Paste the server URL and save.
2. **Approve in the browser.** Openhandle opens in a tab and asks you to approve the connection. Pick Test or Live on that screen.
3. **Ask for social data.** The tools show up in the chat. Ask in plain words and the agent picks the right one.

### Claude Code

```bash
claude mcp add --transport http openhandle https://api.openhandle.dev/mcp
```

1. **Run one command.** This registers the server for the current project.
2. **Sign in once.** Type /mcp in Claude Code and pick openhandle. Your browser opens, you approve, and you pick Test or Live. Headless setups can pass an API key with --header "Authorization: Bearer $OPENHANDLE_TEST_KEY" instead.
3. **Ask for social data.** The tools show up in the chat. Ask in plain words and the agent picks the right one.

### Cursor

```json
{
  "mcpServers": {
    "openhandle": {
      "url": "https://api.openhandle.dev/mcp"
    }
  }
}
```

1. **Add the server to mcp.json.** Create or edit .cursor/mcp.json in your project and paste this in.
2. **Sign in when Cursor asks.** Cursor shows a sign-in prompt next to the server. Approve in the browser and pick Test or Live.
3. **Ask for social data.** The tools show up in the chat. Ask in plain words and the agent picks the right one.

### VS Code

```json
{
  "servers": {
    "openhandle": {
      "type": "http",
      "url": "https://api.openhandle.dev/mcp"
    }
  }
}
```

1. **Add the server to mcp.json.** Create or edit .vscode/mcp.json in your project and paste this in.
2. **Start it and sign in.** Click Start above the server entry. VS Code opens the browser, you approve, and you pick Test or Live.
3. **Ask for social data.** The tools show up in the chat. Ask in plain words and the agent picks the right one.

### Windsurf

```json
{
  "mcpServers": {
    "openhandle": {
      "serverUrl": "https://api.openhandle.dev/mcp"
    }
  }
}
```

1. **Add the server to mcp_config.json.** Open the MCP settings in Windsurf, edit the config file, and paste this in.
2. **Sign in when asked.** Windsurf opens the browser for the sign-in. Approve and pick Test or Live.
3. **Ask for social data.** The tools show up in the chat. Ask in plain words and the agent picks the right one.

Try this prompt first: Find a public Instagram profile in the test data and show me its follower count and last three posts.

The approval screen creates one API key named after the client, for example Claude (MCP). Disconnect a client under Settings, MCP server in the dashboard. That revokes the key and every token at once.

## Tools

| Platform | Tools | Examples |
|---|---|---|
| Instagram | 45 | `instagram_get_profile`, `instagram_list_profile_posts`, `instagram_list_post_comments` |
| TikTok | 28 | `tiktok_get_profile`, `tiktok_search_posts`, `tiktok_list_trending_posts` |
| X | 17 | `twitter_get_profile`, `twitter_list_followers`, `twitter_search_posts` |

- `find_test_data`: Find stable synthetic inputs by platform, operation, or trait. Unmetered.
- `get_test_data`: Get one synthetic catalog entry by its stable ID. Unmetered.

Every result carries the same metadata, so your agent can tell you what a call cost. Fields: `environment`, `requestId`, `actualCharge`, `liveEquivalentPrice`, `datasetVersion`.

## What it costs

- No MCP markup. A tool call costs the same as the matching REST call. There is no extra charge for MCP.
- Older answers cost less. Cache hits cost $0.0005 at 24 hours and $0.0001 at 7 days. A 30-day cache hit is free.
- Failed requests are free. Provider errors, our errors, invalid input, and rate limits cost nothing.
- Test is always free. Every tool works on synthetic data in Test. The actual charge is always zero.

Rates: https://openhandle.dev/pricing.md

## OAuth details

| Document | URL |
|---|---|
| Protected resource metadata | `https://api.openhandle.dev/.well-known/oauth-protected-resource/mcp` |
| Authorization server metadata | `https://api.openhandle.dev/.well-known/oauth-authorization-server` |
| Dynamic client registration | `https://api.openhandle.dev/oauth/register` |
| Authorization | `https://api.openhandle.dev/oauth/authorize` |
| Token | `https://api.openhandle.dev/oauth/token` |
| Revocation | `https://api.openhandle.dev/oauth/revoke` |

- Grant types: authorization_code with PKCE (S256), refresh_token
- Scope: mcp
- Access token: Lives for 1 hour
- Refresh token: Rotates on every use, lives for 30 days
- Resource indicator: resource=https://api.openhandle.dev/mcp

## FAQ

### Does it work with ChatGPT?

Yes. Any client that speaks remote MCP over Streamable HTTP works. Paste the server URL in the connector settings, approve in the browser, and the tools show up in the chat.

### Do I need an environment setting?

No. The credential picks Test or Live. With OAuth you choose on the approval screen. With an API key the key prefix decides. There is no environment argument, header, or setting.

### Can a script use it without OAuth?

Yes. Send an API key as the bearer token in the Authorization header. Test keys start with oh_test_ and are never charged.

### Is the tool list the same as the REST API?

Yes. Every public endpoint is one tool. The tool name comes from the operation ID, such as instagram_get_profile. Inputs and answers match the REST API.

### Where do I see what my agent spent?

In the dashboard under Request history. MCP calls show up with channel mcp. Each row has the tool, the environment, and the charge.

Docs: https://openhandle.dev/docs/mcp.md · Test with MCP: https://openhandle.dev/docs/test-environment/mcp.md