MCP Integration

Overview

The PostGrad MCP server gives your AI agent direct access to structured knowledge feeds. It exposes:

• 5 Tools — Search, browse recent entries, get category summaries, list feeds, and subscribe to feeds
• 4 Resources — Discoverable reference data (feed directory, feed details, entries, stats)
• 2 Prompts — Pre-built templates for business strategy and deal evaluation

All communication happens over HTTPS using the Model Context Protocol remote transport. No local server process is required.

Two ways to connect

PostGrad's MCP server accepts both OAuth 2.1 custom connectors (no API key required — the client walks the user through a login + consent flow) and raw Bearer API keys (for CLI tools and configs that prefer a static credential).

Both paths hit the same /api/mcp endpoint and expose the same tools.

Option A — Custom connector (OAuth)

Supported clients: ChatGPT, Cursor. Claude web and Claude Desktop are currently blocked by an Anthropic-side bug — see the warning below.

1. In ChatGPT, Cursor, or another OAuth-capable client, open the custom-connector dialog.
   • ChatGPT: Settings → Connectors → Add custom MCP → paste the URL below.
   • Cursor: Settings → MCP → Add custom connector → paste the URL below.
2. Paste the MCP URL:

   https://postgrad.io/api/mcp

3. The client will redirect you to PostGrad. If you're not already signed in, you'll land on the login page; sign in with the same account you used to subscribe to feeds.
4. On the consent screen, confirm you want the client to access your subscribed feeds. Click Allow.
5. You're done — the client has a short-lived access token and will auto-refresh it for as long as you stay connected.

Revoking access: go to postgrad.io/dashboard/settings to see all authorized clients and revoke any of them (coming soon in the admin UI; in the meantime contact support).

What the client can do: search, browse, and list categories/feeds across every feed you're actively subscribed to. Rate limits match your subscription tier. The client cannot create, modify, or delete any data.

Under the hood: standard OAuth 2.1 + PKCE with dynamic client registration (RFC 7591). Discovery metadata is at https://postgrad.io/.well-known/oauth-authorization-server and https://postgrad.io/.well-known/oauth-protected-resource.

Option B — API key Bearer

Supported clients: Claude Code CLI, npx add-mcp, any client that lets you set raw HTTP headers.

Prerequisites

1. Create an account at postgrad.io
2. Subscribe to a plan (Starter, Pro, or Scale) — or subscribe to a free feed
3. Generate an API key from your Dashboard
4. Your key will look like: pg_live_xxxxxxxxxxxxx

Client Configuration

Claude Code CLI

Run:

claude mcp add postgrad --transport http https://postgrad.io/api/mcp \
  --header "Authorization: Bearer pg_live_xxxxxxxxxxxxx"

Or add to your .mcp.json manually:

{
  "mcpServers": {
    "postgrad": {
      "type": "remote",
      "url": "https://postgrad.io/api/mcp",
      "headers": {
        "Authorization": "Bearer pg_live_xxxxxxxxxxxxx"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings at .cursor/mcp.json:

{
  "mcpServers": {
    "postgrad": {
      "url": "https://postgrad.io/api/mcp",
      "headers": {
        "Authorization": "Bearer pg_live_xxxxxxxxxxxxx"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP settings:

{
  "mcpServers": {
    "postgrad": {
      "url": "https://postgrad.io/api/mcp",
      "headers": {
        "Authorization": "Bearer pg_live_xxxxxxxxxxxxx"
      }
    }
  }
}

Available Tools

search_knowledge

Search knowledge entries across one or all of the user's subscribed feeds. Supports three search modes — keyword, semantic, and hybrid — each with different strengths and tier requirements. See Search modes explained below for how to pick.

Search modes explained

PostGrad's search engine ships three retrieval strategies. Each one has a different way of deciding "does this entry match the query?" — so the right mode depends on what the query looks like and how valuable precision is to your agent.

keyword — exact lexical matching

How it works: Postgres full-text search (tsvector + ts_rank). The query is tokenized into terms and scored against entries that contain those exact tokens.

Best for:

• Known-term lookups — SKUs, model numbers, acronyms, product names: "SOC 2", "SKU-1234", "GPT-5".
• Short queries where the words ARE the signal.
• Anywhere you want predictable, explainable results that a non-technical user can verify by eye.

Trade-offs:

• Blind to paraphrasing. "how do I cancel my subscription" and "subscription cancellation procedure" may rank different entries.
• Misses synonyms. A query for "laid off" won't surface entries that only say "terminated".

Cost: free — no embedding generation. Fastest mode.

semantic — conceptual / paraphrase matching

How it works: both the query and every knowledge entry are converted into 768-dimensional vector embeddings (Gemini text-embedding-004), then ranked by cosine distance in pgvector. Two texts with similar MEANING sit close together in vector space even if they share no exact words.

Best for:

• Natural-language questions from human users or general-purpose agents.
• Queries where the user doesn't know the exact terminology the entry uses.
• Cross-lingual queries (to the extent the embedding model handles the language pair).

Trade-offs:

• Embeddings cost an API call per unique query. PostGrad caches query embeddings for 24 hours (Upstash, keyed by SHA-256 of query text) so repeat queries are free.
• Can miss exact-term matches. A query for literal "SKU-1234" may rank a conceptually-related entry above the one that literally contains the SKU.
• "Confidently wrong" failure mode: semantic match scores look high even when no entry is actually relevant. Use confidence_min to filter.

Cost: Pro tier and above. ~50-100ms of extra latency on cold-cache queries.

hybrid — Reciprocal Rank Fusion (RRF) of keyword + semantic

How it works: runs BOTH the keyword search and the semantic search in a single Postgres round-trip, then combines the two ranked lists using Reciprocal Rank Fusion with k=60. An entry that ranks highly in either list (or moderately well in both) floats to the top.

Best for:

• Production agents with unknown / diverse query distributions.
• Use-cases where you need defensibility — "we ran it both ways and this is what came up top on average."
• Query patterns that mix natural-language questions and exact-term lookups.

Trade-offs:

• Strictly more expensive than either mode alone (two rankings, one fusion).
• The RRF score is opaque — it's not a confidence score, it's a rank-combination metric, so don't show it to end users.

Cost: Scale tier only. Ships the best quality of the three modes on heterogeneous query distributions.

Picking a mode in one sentence

• You know the exact words you're searching for: keyword.
• You want natural-language / conceptual matching: semantic.
• You're building a general-purpose agent and want the retrieval layer to handle whatever the user throws at it: hybrid.

Search mode access by tier:

When a request is blocked, the response body includes required_tier (which plans would accept the mode) and current_tier, so clients can surface a precise upgrade prompt. Retry the same query with mode=keyword if you want a result on the current tier:

{
  "data": null,
  "error": {
    "code": "TIER_INSUFFICIENT",
    "message": "mode=hybrid requires a scale tier API key. Your key is on starter. Upgrade at https://postgrad.io/pricing, or retry with mode=keyword.",
    "details": {
      "reason": "TIER_INSUFFICIENT",
      "required_tier": ["scale"],
      "current_tier": "starter"
    }
  }
}

There is no silent fallback. If your tier doesn't support the mode you asked for, the request fails with 403 instead of returning keyword results under the hood — so your agent's retry logic can make an explicit decision.

get_recent_knowledge

Get recently added or updated knowledge entries within a feed. Useful for checking what new insights have been extracted.

get_category_summary

Get a summary of a specific category within a feed — entry count, common tags, and sample entries.

list_feeds

Browse available data feeds in the PostGrad marketplace. Returns feeds you're subscribed to and optionally other available feeds.

subscribe_feed

Subscribe to a feed to access its knowledge entries. Free feeds are subscribed instantly. Paid feeds return a checkout URL.

Available Resources

Resources provide discoverable reference data that MCP hosts can pre-load.

Available Prompts

Prompts provide structured templates for common use cases.

business_strategy_advisor

Get strategic business advice grounded in real operator experience.

deal_evaluator

Evaluate a business deal or partnership opportunity.

Troubleshooting

Invalid API Key

• Verify your key starts with pg_live_
• Check that the key is active in your PostGrad dashboard
• Ensure the Authorization header uses the Bearer prefix

Rate Limiting

If rate limited, wait and retry. Upgrade your tier for higher limits.

Connection Timeout

• The MCP endpoint supports up to 60 seconds per request
• For large result sets, use the limit parameter to reduce response size
• Check your network connection and firewall settings

Empty Results

• For search_knowledge, try feed_id: "all" to fan out across every subscribed feed, or omit feed_id to let PostGrad auto-select
• Verify the category name matches one of the feed's categories
• Check that your tier has access to the requested search mode
• Try broadening your search query