# Linkhouse MCP server - connect Claude, ChatGPT or Claude Code to your account

The Linkhouse MCP server lets an AI assistant (Claude, ChatGPT) work on your Linkhouse account: search the offers marketplace, check sites, price orders, create carts or buy from the balance, send guidelines and approve texts. It uses the Linkhouse API `/v1` under the hood, with the same limits and permissions.

You do not paste an API key into the assistant. You log in to the Linkhouse panel once, choose what the assistant may do, and the assistant gets its own access that you can revoke at any time.

## Requirements

- API access enabled for your account. If it is not, the connection screen says so - your account manager can enable it.
- You connect as the account owner, logged in to the Linkhouse panel. Linkhouse support staff cannot connect an assistant to a client account.

## Server address

```
https://app.linkhouse.co/mcp
```

Transport: Streamable HTTP. Authorization: OAuth 2.1 (the assistant finds and handles it on its own).

## How to connect

**Claude (claude.ai, desktop app):** Settings → Connectors → Add custom connector. Paste the server address and click Connect.

**ChatGPT:** add a custom connector (app) with the server address in the ChatGPT settings. Depending on your plan, custom connectors may require developer mode.

**Claude Code:** add the server in the terminal, then run `/mcp` in Claude Code and choose Authenticate:

```
claude mcp add --transport http linkhouse https://app.linkhouse.co/mcp
```

After that the assistant opens the Linkhouse panel in your browser:

1. Log in to Linkhouse, if you are not logged in.
2. Check the name of the application on the screen (Claude, ChatGPT, or the name of a local app such as Claude Code, marked "local app"). Approve only if you have just started connecting Linkhouse yourself. If someone sent you the link, deny.
3. Choose the access type (below) and click Approve.

## Access types

| Type | What the assistant can do |
|---|---|
| Read only | search and read: marketplace, sites, prices, projects, orders, texts, activity; price orders without placing them |
| Cart only (default for orders) | everything above, plus changes in projects, wishlists and exclusions, guidelines, text approval, offer builder, backlink gap; an order creates a shared cart that you pay in the panel - no money is taken from your balance |
| Purchase | everything above, but an order is paid from your balance (then from the debit limit) |

The access types are the same as for API keys.

With the Read only type the assistant does not even see the tools that change data.

## What the assistant can do

| Area | Tools |
|---|---|
| Account | `get_account` (limits, balance, currency), `get_dictionaries` (filter values), `get_activity`, `get_agent_guide` (how to work for a Linkhouse user) |
| Marketplace | `search_sites`, `count_sites`, `get_site`, `check_urls`, `search_mentions` |
| Projects | `list_projects`, `create_project`, `get_project_wishlist`, `add_to_project_wishlist`, `remove_from_project_wishlist`, `get_project_exclusions`, `replace_project_exclusions` |
| Orders | `quote_order` (price without ordering), `place_order`, `list_orders`, `get_order`, `assign_order_to_project` |
| Guidelines and texts | `get_order_guidelines_schema`, `send_order_guidelines`, `revert_order_guidelines`, `get_order_content`, `approve_order_content`, `reject_order_content` |
| Analyses | `start_offer_builder`, `get_offer_builder`, `start_backlink_gap`, `select_backlink_gap_competitors`, `get_backlink_gap` |

Tools that buy, send guidelines, approve or reject texts, or remove data are marked as destructive. Most assistants ask for your confirmation before such a tool, depending on their settings; with the Purchase type keep these confirmations on.

## Orders: how buying stays safe

- The assistant first prices the items with `quote_order` and shows you the items and the total.
- `place_order` requires the price from that quote for every item. If a price changed in the meantime, nothing is ordered and the assistant gets the current prices.
- A retried call with the same items does not order twice: for 7 days the same items return the result of the first order, marked as "no new order or cart was created". To buy the same items again on purpose, confirm it to the assistant - it will repeat the order with a new identifier.
- Offer descriptions and article texts are written by publishers. The assistant is instructed to treat them as data, not as instructions, but with the Purchase type always check the items and the total before you confirm.

## Limits

The assistant uses the limits of your account, shared with your API keys:

- credits, daily limits (new domain analyses, offer builder jobs, projects, carts) and order value limits,
- rate limit per minute for the account.

`get_account` shows the current limits and usage.

## Managing connections

- **List and revoke:** Linkhouse panel → API settings → Connected apps. You see each application, its access type, when it was connected, last used and when the access expires. Revoke cuts the assistant off immediately.
- **Changing the password** revokes all connected applications.
- **API access disabled by Linkhouse** stops all connections. After access is restored, connect the application again if it asks for it.
- **Activity:** the Activity tab in the panel (and `GET /v1/activity`, field `app`) shows which assistant did each action.
- **Expiry:** a connection that is not used for 30 days expires. Connect the application again.
- To change the access type, revoke the connection and connect again with a different type.

## Troubleshooting

| What you see | Why | What to do |
|---|---|---|
| "Your account has no access to the Linkhouse API" on the connection screen | API access is not enabled for the account | ask your account manager |
| "Only the owner of a client account can connect an AI assistant" | you are logged in as Linkhouse support or into someone else's account | log in to your own account |
| The assistant says the connection is invalid or asks to connect again | the connection was revoked, expired (30 days without use), the password was changed or API access was disabled | connect again |
| `READ_ONLY_KEY` or a missing tool | the Read only type does not allow changes | reconnect with Cart only or Purchase |
| `TOO_MANY_REQUESTS`, `DAILY_LIMIT_EXCEEDED` | a limit of the account was reached | wait for the reset; limits are shown by `get_account` |

## For developers

- Server: `POST /mcp`, JSON-RPC 2.0, stateless (no SSE stream, no session). Protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26`.
- Discovery: `401` with `WWW-Authenticate: Bearer resource_metadata=...`, `/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`.
- OAuth 2.1: dynamic client registration (`/oauth/register`), authorization code with PKCE (S256 only), `iss` in the authorization response (RFC 9207), refresh token rotation. Access tokens are valid for 1 hour, refresh tokens for 30 days from the last use.
- Redirect URIs are limited to Claude (claude.ai, desktop app), ChatGPT and local clients that return to `http://localhost:<port>/callback` or `http://127.0.0.1:<port>/callback` (e.g. Claude Code). Other redirect addresses are rejected; to integrate your own software, use an API key and `/v1` directly (`GET /v1/docs/ai-guide.md`).
- Tool input schemas are generated from `GET /v1/docs/openapi.json`; tool results are the `/v1` response envelope (`structuredContent`), with `isError: true` for HTTP errors.
