MCP & Agent Tools

Overview

PinBuilds includes a remote Model Context Protocol (MCP) endpoint for AI agents and coding assistants. Use it to generate Pinterest pins, check article status, list profiles and boards, inspect usage, and schedule pins from tools such as Codex, Claude Code, Cursor, VS Code/GitHub Copilot, Windsurf, Hermes Agent, Gemini CLI, ChatGPT Apps, and other MCP-compatible clients.

The MCP endpoint uses the same server-side logic as the Dashboard, REST API, and WordPress plugin. Profile defaults, Pinterest account settings, board selection, pins per post, scheduling windows, and monthly limits remain controlled in PinBuilds.

Endpoint

Production:

https://pinbuilds.com/api/mcp

Local development:

http://localhost:5173/api/mcp

Authentication uses a PinBuilds API key:

Authorization: Bearer pb_live_your_key_here

Create API keys in Settings > API Keys. Keys are shown once and can be revoked any time.

Available MCP Tools

Recommended Agent Workflow

When using an AI agent:

1. Call get_usage first to confirm remaining quota.
2. Call list_profiles if the source site or Pinterest account is ambiguous.
3. Call check_article_status before bulk or backlog generation.
4. Ask for confirmation before tools that consume quota or create scheduled pins:
   • generate_pins_for_url
   • generate_and_schedule_post
   • schedule_generated_pins
5. Use generate_pins_for_url when you want to review pins before scheduling.
6. Use generate_and_schedule_post when you want PinBuilds to generate and schedule through the matching profile automatically.

Generic MCP Config

Use this template for clients that support remote HTTP MCP servers:

{
  "mcpServers": {
    "pinbuilds": {
      "type": "http",
      "url": "https://pinbuilds.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${PINBUILDS_API_KEY}"
      }
    }
  }
}

Set PINBUILDS_API_KEY to a PinBuilds API key that starts with pb_live_.

Codex

Use the Codex plugin wrapper in the repository:

integrations/codex/

It includes:

• a Codex plugin manifest;
• a PinBuilds skill;
• instructions to connect the remote MCP endpoint.

Recommended Codex prompt:

Use PinBuilds to check usage, generate Pinterest pins for approved article URLs, and schedule approved pins through the configured site profile. Ask before using quota or creating scheduled pins.

For public distribution, use OAuth account linking instead of asking users to paste API keys into marketplace flows.

Claude Code

Use the Claude Code wrapper:

integrations/claude-code/

It includes setup notes and slash command prompts:

• /pinbuilds:generate
• /pinbuilds:schedule
• /pinbuilds:status

Claude Code MCP config:

{
  "mcpServers": {
    "pinbuilds": {
      "type": "http",
      "url": "https://pinbuilds.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${PINBUILDS_API_KEY}"
      }
    }
  }
}

Cursor

Use:

integrations/cursor/mcp.json

Config:

{
  "mcpServers": {
    "pinbuilds": {
      "type": "http",
      "url": "https://pinbuilds.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${PINBUILDS_API_KEY}"
      }
    }
  }
}

After adding the MCP server, ask Cursor to use PinBuilds for article status checks, generation, or scheduling.

VS Code and GitHub Copilot

Use:

integrations/vscode/mcp.json

The template uses VS Code's input prompt pattern so the API key can be entered as a hidden value:

{
  "servers": {
    "pinbuilds": {
      "type": "http",
      "url": "https://pinbuilds.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:pinbuilds-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "pinbuilds-api-key",
      "type": "promptString",
      "description": "PinBuilds API key",
      "password": true
    }
  ]
}

Use this with Copilot Chat Agent mode after MCP support is enabled in your VS Code setup.

Windsurf

Use:

integrations/windsurf/mcp_config.json

Config:

{
  "mcpServers": {
    "pinbuilds": {
      "serverUrl": "https://pinbuilds.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${PINBUILDS_API_KEY}"
      }
    }
  }
}

Hermes Agent

Use:

integrations/hermes-agent/

Hermes Agent supports remote HTTP MCP servers through ~/.hermes/config.yaml. Add:

mcp_servers:
  pinbuilds:
    url: "https://pinbuilds.com/api/mcp"
    headers:
      Authorization: "Bearer ${PINBUILDS_API_KEY}"
    timeout: 180
    connect_timeout: 30
    enabled: true
    supports_parallel_tool_calls: false

Then launch Hermes with:

export PINBUILDS_API_KEY="pb_live_your_key_here"
hermes chat

This does not need a native Hermes Python plugin. Hermes auto-discovers the PinBuilds MCP tools from the remote endpoint. See the Hermes Agent MCP docs for the upstream config reference.

Gemini CLI

Use:

integrations/gemini-cli/

Recommended instruction:

Use PinBuilds for Pinterest pin generation and scheduling. Check usage before generation. Ask for confirmation before tools that consume quota or create scheduled pins.

ChatGPT Apps

The MCP endpoint is the shared tool backend for a future ChatGPT App. Public ChatGPT App distribution should use OAuth user linking rather than API-key copy/paste.

Required production scopes:

usage:read
profiles:read
boards:read
pins:read
articles:read
pins:generate
pins:schedule

The same confirmation rules apply: the app should ask before consuming generation quota or creating scheduled pins.

MCP Registry

The repository includes a registry metadata template:

integrations/mcp/mcp-registry-server.json

Use it when publishing PinBuilds to the official MCP Registry or MCP client directories.

Security Notes

• Do not paste OpenRouter, Runware, Fal, Pinterest, Cloudflare R2, database, or provider secrets into agent tools.
• Agent clients only need a PinBuilds API key or an OAuth-linked PinBuilds account.
• Revoke old API keys from Settings > API Keys if a local tool or machine is no longer trusted.
• Generation and scheduling are still protected by PinBuilds subscription access, monthly limits, rate limits, and profile-domain matching.