---
title: MCP Server
url: https://www.plushcap.com/docs/mcp
updated: '2026-11-03T12:01:56.209708+00:00'
description: Compare MCP clients and connect them to Plushcap with a Bearer token
  or OAuth.
---

# MCP Server

Compare MCP clients and connect them to Plushcap with a Bearer token or OAuth.

Connect an MCP-compatible AI client to Plushcap to query company engineering
blogs, YouTube metrics, Hacker News posts, and industry trends.

Effective Accelerate access (including qualifying trials, organization grants, Lead, and staff access) includes paid tools for full trend reports, competitive spaces and comparisons, and monthly and yearly trend metrics:

- `get_trend_report` (full report content)
- `list_competitive_spaces` and `get_competitive_space`
- `get_competitive_space_comparison` and `compare_companies`
- `get_monthly_trend_metrics` and `get_yearly_trend_metrics`

**Server URL:**

`https://mcp.plushcap.com/mcp`

## Choose an authentication method

Plushcap MCP supports two authentication methods:

- **Bearer token — recommended for ongoing use.** Create a Plushcap API key
  from your [account](/account) and configure the client to send it in the
  `Authorization` header. API keys do not expire by default; they remain active
  until you regenerate, delete, or explicitly expire them.
- **OAuth — fastest to get started.** Authorize the client in your browser.
  Plushcap OAuth access tokens last one hour. Clients that request
  `offline_access` receive a rotating refresh token with a 90-day lifetime,
  but you may need to authorize again when a refresh credential expires, is
  lost, or is not refreshed correctly by the client.

MCP API-key authentication uses:

```http
Authorization: Bearer your-api-key-here
```

This differs from the Plushcap REST API, which uses `X-API-Key`. Prefer an
environment variable or a client's secret field over putting the key directly
in a configuration file. Never commit the key or paste it into a chat prompt.
Regenerate it from your account if it is exposed.

## Compare MCP clients

| Client | MCP support | OAuth | Bearer token | Recommended setup |
|---|---|---:|---:|---|
| [ChatGPT Web](/docs/mcp/chatgpt-web.md) | Supported | Yes | No custom API keys | OAuth |
| [ChatGPT Desktop](/docs/mcp/chatgpt-desktop.md) | Supported | Yes | Yes | Bearer token |
| [Claude Desktop](/docs/mcp/claude-desktop.md) | Supported | Yes | No direct header setting | OAuth |
| [Claude Web](/docs/mcp/claude-web.md) | Supported | Yes | No direct header setting | OAuth |
| [Claude Code](/docs/mcp/claude-code.md) | Supported | Yes | Yes | Bearer token |
| [Codex CLI](/docs/mcp/codex-cli.md) | Supported | Yes | Yes | Bearer token |
| [Antigravity CLI](/docs/mcp/antigravity-cli.md) | Supported | Yes | Yes | Bearer token |
| [Devin](/docs/mcp/devin.md) | Supported | Yes | Yes | Bearer token |
| [Gemini Web](/docs/mcp/gemini-web.md) | Limited to Gemini Spark | Yes | No documented header setting | OAuth |
| [Gemini Enterprise](/docs/mcp/gemini-enterprise.md) | Admin setup; requires PKCE | Yes | No documented header setting | OAuth client credentials |
| [Gemini Desktop](/docs/mcp/gemini-desktop.md) | No direct setup documented | No | No | Use another client |
| [LM Studio](/docs/mcp/lm-studio.md) | Supported | Yes | Yes | Bearer token |

If your client supports both methods, start with OAuth for a quick test and
switch to a Bearer token for a connection that does not depend on the client's
OAuth refresh behavior.

## Verify the connection

After setup, ask your client:

```text
Use Plushcap to list the latest developer industry trend reports.
```

## Health Check

Confirm the MCP service is online at:

```text
https://mcp.plushcap.com/health
```

Last verified: July 29, 2026.


## X Content Research Tools

The authenticated server also registers `list_company_x_accounts`,
`get_company_x_posts`, `get_company_x_post`, `get_company_x_summary`,
`find_high_engagement_x_posts`, `research_company_x_content`, and
`get_global_hackernews_posts`. These tools require at least Free access and
forward only validated read parameters. The composite research tool makes one
REST call and returns evidence; the calling model is responsible for critiques
and recommendations.

## Global Content Search and YouTube Research

Use `search_youtube_videos` and `search_x_posts` for intersecting multi-company searches. Use `research_company_youtube_content` for one evidence-only composite call; the calling model owns all advice.

## Access errors and recovery

Expected access and quota denials include `schema_version: 1`, `code`,
`error_type`, `message`, `capability`, `current_tier`, `required_tier`,
`retryable`, `wait_will_help`, `resets_at`, `retry_after_seconds`, `free_limit`,
`free_alternatives`, and `upgrade`. REST also preserves `detail` and existing
quota fields. MCP returns the JSON in a text content block with `isError: true`;
successful tool output schemas are unchanged.

Wait only when `wait_will_help` is true. A Free hourly quota error includes the
actual UTC reset time and remaining seconds, also carried in REST's
`Retry-After` and `X-RateLimit-Reset` headers. Each metered endpoint has a separate
allowance shared by the user's API keys and MCP connections. Company profiles
remain available through `get_company` and the companies API.

A paid capability denial explains the restriction and says waiting will not
help. Paid request parameters are checked before consuming the Free allowance.
Record-dependent X detail lookups use that allowance, and exhausted callers get
429 before any post lookup. Invalid trend modes return 400 without using quota.
Explain
the specific capability and offer a listed Free alternative when useful.
Reconnecting is appropriate for credential failures, not a plan restriction.

When `upgrade` is present, use its capability benefit, current price (when
available), and subscription link. `required_tier` describes minimum access:
Free quota exhaustion still requires only Free access, with Accelerate as an
optional way to remove that allowance. Prices are USD per month, resolved from
the current active billing price and cached briefly; missing prices are null.
Do not invent prices or recommend upgrading for unknown failures or outages.
Manage access at [Subscription](/subscription) or review [Pricing](/pricing).

## Plan access and shared limits

MCP uses the connected user's effective Plushcap access. OAuth and API-key
connections share the same account allowance with the REST API: **five requests
per metered endpoint per clock hour** for Free accounts, resetting at the top of
each UTC hour. All companies and IDs queried through an endpoint share its
counter. Changing clients or reconnecting does not create a new allowance.
Effective Accelerate or Lead access, qualifying trials and organization grants,
and staff access bypass that allowance.

`list_companies`, `get_company`, and `get_trend_topics` do not use the hourly
allowance. `list_trend_reports` is also available to authenticated Free accounts
without the quota: it lists report metadata, including paid report summaries,
but excludes staff-only reports and full content. `get_trend_report` requires
paid effective access and still respects the individual report's access level.

`search_youtube_videos`, `research_company_youtube_content`,
`list_company_youtube_videos`, and `get_company_youtube_video` require
Accelerate access and return `youtube_paid_access_required` for a Free account.
`get_company_youtube` has limited Free access; explicit paid date or pagination
parameters are rejected before consuming its allowance.

`get_company_x_post` uses one call even if a looked-up post is missing or older
than Free's 14-day history boundary. After five calls it returns a quota error
before looking up the ID. Explicit paid X range parameters are rejected before
charging a call. See [X access and quotas](/docs/x.md#free-access-and-quotas).

Expected tool access failures return `isError: true` with JSON in a text content
block. Check `code`, `capability`, `required_tier`, and `wait_will_help`.
For quota errors, wait until `resets_at` or use `retry_after_seconds`; for paid
capability errors, waiting or reconnecting will not help. A listed Free
alternative can still have its own allowance. Use an upgrade's returned benefit,
price when present, and subscription link; do not invent a price or upgrade
recommendation for an unknown failure. Successful tool result schemas are
unchanged. See [the shared quota rules](/docs/authentication.md#free-hourly-allowance).

## Machine-readable REST description

The [OpenAPI 3.1 description](/api/v1/openapi.json) covers published customer GET operations, parameters, response shapes, and effective access. REST accepts the `X-API-Key` header or a Django session cookie. Missing credentials on restricted reads and invalid or expired keys return HTTP 403. Public company and topic discovery remains anonymous.

## Documentation pages

- [Docs](/docs.md)
- [Tools](/docs/mcp/tools.md)
- [ChatGPT Web](/docs/mcp/chatgpt-web.md)
- [ChatGPT Desktop](/docs/mcp/chatgpt-desktop.md)
- [Claude Desktop](/docs/mcp/claude-desktop.md)
- [Claude Web](/docs/mcp/claude-web.md)
- [Claude Code](/docs/mcp/claude-code.md)
- [Codex CLI](/docs/mcp/codex-cli.md)
- [Antigravity CLI](/docs/mcp/antigravity-cli.md)
- [Devin](/docs/mcp/devin.md)
- [Gemini Web](/docs/mcp/gemini-web.md)
- [Gemini Enterprise](/docs/mcp/gemini-enterprise.md)
- [Gemini Desktop](/docs/mcp/gemini-desktop.md)
- [LM Studio](/docs/mcp/lm-studio.md)
