> ## 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 14 typed tools. It works with Claude Desktop, Cursor, ChatGPT Connectors, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io)-compatible client.

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 14 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

| 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`                          |

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 (Apps & Connectors)

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

### 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                                                                 |

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

* **Trust tool descriptions.** Each tool's `description` is written for the LLM. It explains when to pick that tool over the others. Don't override or rewrite it client-side.
* **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.
* **Cache `get_creator` and `get_profile`.** Both are cheap, and creator/profile data doesn't change often. If your agent runs many sessions for the same user, cache.

## 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>