MCP server
This is the OG Pilot MCP install guide. Add the remote server, approve OAuth, and ask the agent for the first social image. The endpoint is https://ogpilot.com/mcp. Debug, compress, and palette work on a guest connector session. generate_og_image needs an active plan.
Use the OG image MCP server when an assistant should call OG Pilot. Use the REST API when your application signs a request on each render. Use the web generator when you have one URL and you will publish the file yourself. The three surfaces do not share a plan check.
| Surface | Use it when | Auth | Input | Result | Plan |
|---|---|---|---|---|---|
| MCP server | An agent in Claude or ChatGPT already has the page URL and should call a tool. | OAuth 2.1 with PKCE. Bearer access token. Scope mcp:generate. No API key in the config. | A public page URL, or a public image URL for compress and palette. | Hosted image URL, a debug report, a CDN URL, or hex colors. Generation can also return image bytes. | generate_og_image needs an active plan and a credit. The other three tools work on a guest connector session. |
| REST API | Your own server should mint an og:image URL while it renders a page. | A JWT in the JSON body field token. You sign it on your server. The API key is the HMAC secret and is not sent. | Claims iss (verified domain) and sub (API key prefix), plus template fields such as title. | A CDN image URL to put in og:image and twitter:image. | The API allows an active subscription, a past-due subscription, or a trial, and the domain must be verified. |
| Web generator | You have one URL and want to paste it in the browser and download a card. | The form at /new. No MCP config and no JWT. | One public page URL. | Branded variations you download or publish by hand. | A browser session. It is not the MCP tool, and it does not start from a connector. |
MCP generation does not burn domain JWT image quota, and it does not open a checkout. Plans are on the pricing section. After you publish a tag, re-check the public URL in the Open Graph debugger.
The only transport is Streamable HTTP. POST JSON-RPC to https://ogpilot.com/mcp. GET does not open an SSE stream. There is no stdio binary, no local command, and no API-key header. A client that can only launch a process cannot connect.
Auth is OAuth 2.1 with PKCE (S256). The client discovers /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, registers at /oauth/register if it does not already have a client id, then opens /oauth/authorize. Leave the OAuth client id and secret blank unless the client asks you to paste values from a failed registration. Supported scopes are mcp:generate and offline_access. All four tools use mcp:generate.
On the consent page, choose Allow. A guest connector session can debug, compress, and extract a palette. To generate an image, use the account link on that page and approve while signed in to an account with an active plan. Access tokens last 1 hour. The token response also includes a refresh token that lasts 90 days. Authorization codes last 10 minutes.
This block is the remote entry the repo ships. Claude and ChatGPT do not read this file. They use the steps under it. Do not add command, args, or a bearer token.
Remote MCP config
{
"mcpServers": {
"og-pilot": {
"type": "streamable-http",
"url": "https://ogpilot.com/mcp"
}
}
}On Team and Enterprise, an owner adds the custom connector under Organization settings, then Connectors. Members then connect from Customize, then Connectors.
Developer mode is for testing a custom MCP server. The settings label moves. Look under Security, Advanced, or workspace permissions. tools/list does not push changes (listChanged is false). Reconnect after a tool update.
The server exposes these four tools and no others. Private, link-local, and metadata addresses are rejected. A failed tool call is still a JSON-RPC result with isError: true and structuredContent.error_code. It is not an HTTP 500.
| Tool | Inputs | Outputs | Limits | Plan |
|---|---|---|---|---|
generate_og_image | Required url. Optional style. Omitted or unknown style uses auto-detect (default). | status, image_url, page_url, title, style. Clients that accept image content also get the preview bytes when they fit in 1.5 MB. | Waits up to about 50 seconds for the first preview, then returns. It does not wait for the second variation. 10 new images per hour. Protocol calls and this tool share 60 requests per hour per access token. | Signed-in account with an active plan and at least one credit. A trial is not enough. Guests get plan_required. |
debug_open_graph | Required url. Public http(s) only. | status, score, score_label, url, meta_tags, image (url, content_type, byte_size, width, height, aspect_ratio), issues, suggested_meta. | About 12 seconds. HTML download stops at 1 MB. Preview image download stops at 4 MB. 30 calls per hour per connector session, inside a shared 40-request free-tool bucket. | Guest connector session. Read-only. Does not spend a credit. |
compress_image | Required image_url (PNG, JPEG, GIF, WebP, or AVIF). No base64. Optional width and height (default 1200×630, max 4096), format (jpeg, png, webp, avif), quality (1–100, default 82), fit (cover, contain, fill, scale-down, crop, or pad; default cover), target_bytes (10 KB–5 MB). | status, image_url, byte_size, width, height, quality, format, and the source size and dimensions. No image bytes. | About 15 seconds. Download stops at 8 MB and 8000 px. 20 calls per hour per connector session, inside the free-tool bucket. When target_bytes is set, quality is searched between 40 and 95. | Guest connector session. Does not spend a credit. Does not use the browser compressor session. |
extract_color_palette | Required image_url, same public image rules as compress. Optional limit from 1 to 8, default 5. | status, colors, swatches, background_color, text_color, contrast_ratio, meets_wcag_aa. | About 12 seconds. Same 8 MB and 8000 px cap. 30 calls per hour per connector session, inside the free-tool bucket. | Guest connector session. Read-only. Does not spend a credit. |
Style keys for generate_og_image: default, minimalistic, modern, vintage, colorful, abstract, geometric, kawaii, flat, comic, anime, van_gogh, watercolor, ballpoint, pencil, pixel_art, retro_game, halloween, thanksgiving, xmas. default is auto-detect. Each new image reserves one credit. Retrying the same URL and style within 30 minutes reuses a generation that is already in flight or finished, instead of reserving another credit. The browser versions of the free tools are the debugger, the image compressor, and the palette extractor.
The server takes one URL per call. It does not clone a repository or walk a sitemap. The agent loops. Ask it to call the tool, then put image_url in the meta tag yourself or in the repo it can edit.
Generate a card for each post. Give the agent the public URLs. It should call generate_og_image once per URL. A timeout means the first preview was not stored yet. The same URL can be retried inside 30 minutes without a second credit.
Example prompt: posts
Use the OG Pilot MCP server. For each of these public URLs, call generate_og_image and give me the image_url:
https://example.com/blog/launch
https://example.com/blog/pricing
If a call returns timeout, retry that same URL once. If it returns plan_required, stop and tell me to pick a plan.Debug a LinkedIn preview, then fix the image. debug_open_graph reads the live tags. It does not clear LinkedIn's cache. If the image is the weak part, compress_image can resize a public image URL to 1200×630, or generate_og_image can draw a new card. Then run the same URL in the debugger.
Example prompt: broken preview
Use OG Pilot. Call debug_open_graph on https://example.com/pricing.
Summarize the score, the og:image URL, and the issues.
If the image is missing or huge, call compress_image on that image URL with width 1200 and height 630.
Do not call generate_og_image unless I have an active plan.Read a brand palette, then generate a card. extract_color_palette returns hex colors and a text/background pair. generate_og_image does not accept those hex values. It accepts a page URL and an optional catalog style. Use the palette to choose a style key, or to check contrast. It does not paint a custom brand color into the image.
Example prompt: palette, then a card
Use OG Pilot. Call extract_color_palette on https://example.com/logo.png with limit 5.
Tell me the hex colors and the text/background pair.
Then call generate_og_image on https://example.com with style modern.
Do not invent a color argument. The generator has no hex input.If the caller is your server, skip MCP and sign a JWT. Required claims are iss (a verified domain) and sub (the API key prefix). Sign with HS256 using the API key as the secret. Field reference and SDK samples are in the API docs. Create the key from an account. A trial can call this API. It cannot call generate_og_image.
API request
curl -X POST "https://ogpilot.com/api/v1/images" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"token":"YOUR_JWT_TOKEN"}'POST /mcp without a valid bearer token returns HTTP 401 and invalid_token. The access token lasts 1 hour. Reconnect so the client can refresh or run the consent flow again. A denied consent page returns access_denied. An unknown client id returns invalid_client. A scope other than mcp:generate or offline_access returns invalid_scope.
The connected session is a guest, the account is on a trial, the subscription is not active, or the credit balance is zero. The tool does not start a checkout. Sign in on the consent page with an account that has an active plan and at least one credit, then connect again. Plans are listed at /#pricing. debug_open_graph, compress_image, and extract_color_palette do not return this error for a guest.
For generate_og_image, timeout means the first preview was not stored within about 50 seconds. The job keeps running. Retry the same URL. A retry inside 30 minutes reuses that generation. Debug stops around 12 seconds, palette around 12, and compress around 15. Those timeouts mean that call itself stopped, not that a preview is still rendering.
Generation is capped at 10 images per hour, and that path shares 60 requests per hour with protocol calls. The three free tools share a separate 40 requests per hour, plus their own caps, so they cannot spend the generation budget. If a tool you expect is absent, reconnect. The server does not push tools/list changes.
Pass a public http or https URL. Localhost, link-local, and metadata addresses are rejected. compress_image and extract_color_palette need an image URL, not a base64 string and not an HTML page.
Connecting the server stores OAuth client and token metadata, the URLs you submit, and the generated or compressed assets. Details are in the privacy policy.
Connect the server, call debug_open_graph on a public URL, then call generate_og_image once the account has an active plan. If the image should be created inside your app, use the API docs instead of MCP.
Add https://ogpilot.com/mcp as a remote Streamable HTTP server and approve OAuth.
Sign JWTs on your server when the caller is your app, not an agent.
generate_og_image needs an active plan and a credit. The tool will not open checkout.
JWT claims, templates, and SDK samples for POST /api/v1/images.
The same inspection as debug_open_graph, in the browser.
Paste one URL in the browser when you do not want a connector.
Connect the MCP server, or paste the domain below to open the browser generator.
Start a trial and ship OG images that earn clicks.