> ## Documentation Index
> Fetch the complete documentation index at: https://docs.influship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect AI agents to the Influship API using the Model Context Protocol

The Influship MCP server exposes the API to AI agents through typed tools. It works with Claude Desktop, Cursor, ChatGPT Connectors, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io)-compatible client.

| Before you start | Details |
| - | - |
| Auth | API key for generic clients; OAuth for account linking |
| Resource | The resources exposed by your configured endpoint |
| Cost | Tool calls use their corresponding [API prices](/concepts/pricing) |
| Limits | Use tools/list; inspect each tool schema and your rate-limit headers |

The server is hosted at `https://mcp.influship.com/mcp` and uses the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) (spec `2025-06-18`). Stdio-only clients connect via the `mcp-remote` bridge.

## How it works

Generic MCP clients authenticate with an Influship API key. Clients that support account linking can use OAuth instead. Calls use the billing route and rate limits associated with the credential.

1. The agent connects to `https://mcp.influship.com/mcp` with an `X-API-Key` or linked Influship account
2. The agent discovers the available typed tools, each with a full description and parameter schema
3. The agent picks the right tool, such as `semantic_search_creators`, and calls it with its arguments
4. The result includes the REST response fields plus MCP-specific `suggested_followups`

Clients can list available tools without authentication. `get_sample_creator` provides an unauthenticated preview. The remaining tools require an API key or OAuth account link.

## Set up with AI

Copy this prompt into your coding agent.

<Prompt description="Connect this project or development environment to the Influship MCP server." actions={["copy", "cursor"]}>
  Connect this development environment to the Influship MCP server.

  First inspect the repository and available MCP configuration to identify the active client and whether configuration belongs at project or user scope. Preserve existing MCP servers.

  Add an MCP server named `influship` using Streamable HTTP:

  * URL: [https://mcp.influship.com/mcp](https://mcp.influship.com/mcp)
  * Header: `X-API-Key: YOUR_INFLUSHIP_API_KEY`

  Use a placeholder only. Never paste, read, print, or commit a real API key. If this client supports environment-variable expansion in MCP headers, use the client's documented syntax for `INFLUSHIP_API_KEY`. Otherwise, explain exactly where I must add the key locally after you finish.

  Verify that the server connects and its tools can be listed. If credentials are available, run a small creator lookup to confirm authenticated tools work. Preserve all unrelated configuration and finish by naming the file or setting changed plus any remaining step I must take.
</Prompt>

## Tools

The table below describes the general `/mcp` endpoint. The account-linked `/plugin/mcp` endpoint exposes a focused creator workspace and saved-shortlist tools; see [ChatGPT setup](#chatgpt). Use your client's tool list for the inventory available on its configured endpoint.

| Tool | Method | Endpoint |
| - | - | - |
| `get_sample_creator` | GET | Configured creator preview |
| `search_creators` | GET or POST | `/v1/creators/autocomplete` or `/v1/search` |
| `semantic_search_creators` | POST | `/v1/search` |
| `autocomplete_creators` | GET | `/v1/creators/autocomplete` |
| `find_lookalike_creators` | POST | `/v1/creators/lookalike` |
| `match_creators` | POST | `/v1/creators/match` |
| `get_creator` | GET | `/v1/creators/:id` or `/v1/profiles/:platform/:username` |
| `get_profile` | GET | `/v1/profiles/:platform/:username` |
| `lookup_profiles` | POST | `/v1/profiles/lookup` |
| `get_posts` | GET | `/v1/posts` |
| `get_instagram_post` | GET | `/v1/raw/instagram/post/:shortcode` |
| `get_instagram_posts` | POST | `/v1/raw/instagram/posts` |
| `get_instagram_post_transcript` | GET | `/v1/raw/instagram/transcript/:shortcode` |
| `get_instagram_post_transcripts` | POST | `/v1/raw/instagram/transcripts` |
| `get_tiktok_profile` | GET | `/v1/raw/tiktok/profile/:username` |
| `get_tiktok_music` | GET | `/v1/raw/tiktok/music` |
| `search_tiktok_users` | GET | `/v1/raw/tiktok/search/users` |
| `search_tiktok_videos` | GET | `/v1/raw/tiktok/search/videos` |
| `list_tiktok_hashtag_videos` | GET | `/v1/raw/tiktok/hashtag/videos` |
| `list_tiktok_music_videos` | GET | `/v1/raw/tiktok/music/videos` |
| `get_tiktok_video_captions` | GET | `/v1/raw/tiktok/video/captions` |
| `list_tiktok_profile_videos` | GET | `/v1/raw/tiktok/profile/:username/videos` |
| `get_tiktok_video` | GET | `/v1/raw/tiktok/video` |
| `list_tiktok_video_comments` | GET | `/v1/raw/tiktok/video/comments` |
| `list_tiktok_comment_replies` | GET | `/v1/raw/tiktok/video/comment/replies` |
| `get_tiktok_video_transcript` | GET | `/v1/raw/tiktok/video/transcript` |
| `get_tiktok_videos` | POST | `/v1/raw/tiktok/videos` |
| `get_tiktok_video_transcripts` | POST | `/v1/raw/tiktok/video/transcripts` |
| `get_youtube_channel` | GET | `/v1/raw/youtube/channel/:handle` |
| `get_youtube_video_transcript` | GET | `/v1/raw/youtube/transcript/:video_id` |
| `get_youtube_channel_transcripts` | GET | `/v1/raw/youtube/channel-transcripts/:handle` |
| `search_youtube` | GET | `/v1/raw/youtube/search` |
| `get_youtube_video` | GET | `/v1/raw/youtube/video/:video_id` |
| `get_youtube_typeahead` | GET | `/v1/raw/youtube/typeahead` |
| `render_creator_shortlist` | Composite | Search page or creator lookups |
| `render_creator_profile` | Composite | Creator and post lookups |
| `render_creator_comparison` | Composite | Creator lookups and match scoring |

Each tool description tells the agent when to use it. Use `semantic_search_creators` for topical or campaign discovery, `search_creators` for a name or partial handle, and `find_lookalike_creators` when you already have seed creators.

## Quickstart

Choose the setup for your client below. Config-based clients need an API key from the [dashboard](https://developers.influship.com); account-linking clients use OAuth.

### Claude Code (CLI)

One command:

```bash theme={null}
claude mcp add influship --transport http https://mcp.influship.com/mcp --header "X-API-Key: YOUR_INFLUSHIP_API_KEY"
```

Add `--scope user` to install across every project, not just the current directory.

### Claude Desktop

Open **Customize → Connectors → Add custom connector**, enter `https://mcp.influship.com/mcp`, then complete Influship account linking when prompted. Claude's remote custom-connector flow uses OAuth rather than an arbitrary API-key header.

If you prefer an API-key-backed local bridge, add this to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "influship": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.influship.com/mcp",
        "--header",
        "X-API-Key:YOUR_INFLUSHIP_API_KEY"
      ]
    }
  }
}
```

### Cursor and Windsurf

Both clients use the same remote-server configuration. Set `INFLUSHIP_API_KEY` in the environment that launches the app, then add this JSON to `.cursor/mcp.json` for Cursor or `~/.codeium/windsurf/mcp_config.json` for Windsurf:

```json theme={null}
{
  "mcpServers": {
    "influship": {
      "url": "https://mcp.influship.com/mcp",
      "headers": {
        "X-API-Key": "${env:INFLUSHIP_API_KEY}"
      }
    }
  }
}
```

### VS Code

Run **MCP: Add Server**, or add the server to `.vscode/mcp.json`. VS Code uses a top-level `servers` object rather than Cursor's `mcpServers` key:

```json theme={null}
{
  "inputs": [
    {
      "type": "promptString",
      "id": "influship-api-key",
      "description": "Influship API key",
      "password": true
    }
  ],
  "servers": {
    "influship": {
      "type": "http",
      "url": "https://mcp.influship.com/mcp",
      "headers": {
        "X-API-Key": "${input:influship-api-key}"
      }
    }
  }
}
```

### ChatGPT

In an eligible workspace, enable developer mode, create a custom app from **Settings → Apps**, and use `https://mcp.influship.com/plugin/mcp` as the remote MCP endpoint. Complete Influship account linking when prompted.

The ChatGPT workspace lets you describe a campaign brief, inspect creator evidence, select up to eight creators, and compare two to four against the brief. Save a named shortlist with notes to your linked account, then resume it from the saved library. Selected creators remain available when you refine a search.

Resume a saved shortlist to retrieve the latest stored creator evidence using your linked account's lookup allowance. Your shortlist keeps selected profiles, the brief, and notes together. Collection dates and evidence labels help you review profile data, content evidence, and AI analysis.

Each account can hold 100 saved shortlists. Updating a shortlist requires its current version; if another save changes it, reopen it before updating. Saved work is private to your linked account. In desktop hosts that support composer mentions, search your saved shortlist names to reference them in a conversation.

### Stdio-only clients

Some clients only support stdio transport. Bridge them with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```bash theme={null}
npx -y mcp-remote https://mcp.influship.com/mcp --header "X-API-Key:YOUR_INFLUSHIP_API_KEY"
```

## Authentication and billing

The MCP server supports two authentication paths:

* Generic clients send `X-API-Key`; calls use the associated API account's metering and rate limits
* Account-linking clients send an OAuth bearer token; calls use the linked account's billing route and allowance
* `get_sample_creator` is an unauthenticated preview and does not expose arbitrary creator data

If you don't have an API key, [create one in the dashboard](https://developers.influship.com).

## Pricing

MCP tool calls bill at the same per-credit price as the underlying REST endpoint. There's no MCP surcharge.

| Tool | Cost |
| - | - |
| `get_sample_creator` | No user charge |
| `search_creators` | 0.05 credits for indexed creator lookup, or the search price when routed to semantic search |
| `semantic_search_creators` | 25 credits + 2 per result returned |
| `find_lookalike_creators` | 1.5 per creator returned |
| `match_creators` | 1 per creator scored |
| `autocomplete_creators` | 0.05 per call |
| `get_creator` | 0.1 per call |
| `get_profile` | 0.1 per call |
| `lookup_profiles` | 0.1 per profile returned |
| `get_posts` | 0.05 per post returned |
| `get_instagram_post` | 1 per post |
| `get_instagram_posts` | 1 per successful post |
| `get_instagram_post_transcript` | 5 per transcript |
| `get_instagram_post_transcripts` | 5 per successful transcript |
| TikTok profile, video, or comments tools | 0.2 per request or source page |
| `get_tiktok_video_transcript` | 2.5 per transcript |
| `get_tiktok_videos` | 0.2 per successful entry; 1–20 URLs |
| `get_tiktok_video_transcripts` | 2.5 per successful auto entry or 0.2 per captions entry; 1–10 URLs |
| `get_youtube_channel` | 0.5 per channel |
| `get_youtube_video_transcript` | 0.5 per transcript |
| `get_youtube_channel_transcripts` | 0.5 per transcript returned |
| `search_youtube` | 0.5 per fetched page |
| `get_youtube_video` | 0.5 per video |
| `get_youtube_typeahead` | 0.5 per request |
| `render_creator_*` | Sum of the REST calls the selected composite tool makes |

One credit is \$0.01. See the [REST pricing reference](/concepts/pricing) for the full breakdown.

## Rate limits

The credential's account limits apply, matching direct REST usage. There's also a per-IP cap of 60 requests per minute. If you hit it, the server returns `429` with a `retry-after` header.

If you're connecting many agents from the same IP (a corporate proxy, for example), reach out and we'll tune the IP cap.

## Error codes

When a tool call fails, the error message is surfaced as readable text in the MCP client.

| Error | Meaning |
| - | - |
| `400` | Missing or invalid parameter |
| `401` | Missing or invalid API key or account authorization |
| `402` | Payment required |
| `403` | Credential valid but lacks permission for this tool |
| `404` | Creator, profile, or post not found |
| `429` | Rate limit exceeded — check `retry_after_seconds` in the response |
| `5xx` | Server or temporary upstream error; live data 503s may include `retry_after_seconds` |

## Anonymous agents (no API key)

For one-off agents without an API key or linked account, use the direct HTTP API with [x402](/guides/x402) or [MPP](/guides/mpp). These payment protocols apply to supported REST endpoints rather than MCP tool calls.

## Implementation tips

* **Use tool descriptions for selection.** Each tool describes its purpose and parameters so your client can choose the appropriate operation.
* **Pass real IDs.** Tools that take a `creator_id` expect a UUID from a previous tool's response. Resolving by `platform + username` is supported on lookalike, match, and posts — useful when the user types a handle.
* **Bound multi-step workflows.** Cursor pagination and composite render tools can make additional billed calls. Set a page or result ceiling before handing control to an autonomous agent.

## Next steps

<CardGroup cols={2}>
  <Card title="Get an API Key" icon="key" href="https://developers.influship.com">
    Sign up and grab your key from the dashboard
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Full endpoint specs and response schemas — the tools mirror these
  </Card>

  <Card title="Pay with x402" icon="bitcoin" href="/guides/x402">
    Anonymous per-request payment for one-off agents
  </Card>

  <Card title="Pay with MPP" icon="credit-card" href="/guides/mpp">
    Stripe cards or Tempo USDC for agent-native payments
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.