BlackOps Remote MCP Server

1. Overview

This project is a production-ready remote MCP server that exposes BlackOps publishing and marketing APIs as MCP tools for Claude Cowork/Claude chat, Claude Code, and other MCP clients. It is a thin wrapper around existing BlackOps REST endpoints with strong validation, normalized responses, and publish-safety confirmations.

2. Features

• Official MCP TypeScript SDK (McpServer) with Streamable HTTP transport.
• Tool groups:
  • Account/Context
  • Tweets + Threads
  • Blogs + SEO helpers
  • Campaigns
  • Notes/Memory
• Zod input validation for each tool.
• Centralized BlackOps API client with timeout + retry behavior.
• Normalized success/error responses.
• Optional bearer-token protection for incoming MCP calls.
• Health and version endpoints.
• Optional tool allowlist via ENABLED_TOOLS.

3. Requirements

• Node.js 20+
• Access to BlackOps REST API (BLACKOPS_API_BASE)
• For stdio/local use: BLACKOPS_API_TOKEN
• For HTTP/remote use: caller Authorization: Bearer <customer_token> on MCP requests (forwarded upstream)

4. Installation

npm install

5. Development

npm run dev

6. Build

npm run build

7. Start

npm start

8. Environment variables

| Variable | Required | Description | | --- | --- | --- | | PORT | no | HTTP port for MCP server (default 3000) | | NODE_ENV | no | development, test, or production | | BLACKOPS_API_BASE | no | Base URL for upstream BlackOps API (default https://api.blackopscenter.com) | | BLACKOPS_API_TOKEN | no | Bearer token used in stdio mode (npx/local connector) | | LOG_LEVEL | no | Pino log level | | SERVER_BEARER_TOKEN | no | Optional bearer token required by /mcp | | REQUEST_TIMEOUT_MS | no | Upstream request timeout in ms | | REQUEST_RETRY_COUNT | no | Retries for transient 429/5xx/network failures | | ENABLED_TOOLS | no | Comma-separated allowlist of tool names |

All upstream requests send:

• Authorization: Bearer <token_from_incoming_mcp_request_or_BLACKOPS_API_TOKEN>
• Content-Type: application/json

9. Using via npx (local stdio MCP)

Use the package as a local stdio server in your MCP client config:

{
  "mcpServers": {
    "blackops": {
      "command": "npx",
      "args": ["blackops-mcp@latest"],
      "env": {
        "BLACKOPS_API_TOKEN": "YOUR_CUSTOMER_BLACKOPS_TOKEN"
      }
    }
  }
}

10. Connecting to Claude Cowork / Claude chat via remote MCP

1. Deploy this service behind HTTPS.
2. Use your remote MCP connector URL pointing to https://<host>/mcp.
3. If SERVER_BEARER_TOKEN is configured, provide it as an Authorization header (Bearer <token>).
4. Claude will discover and call tools registered by this server.

11. Connecting to Claude Code

claude mcp add --transport http blackops https://your-server.example.com/mcp

If protected, configure bearer auth according to your Claude Code MCP auth settings.

12. Tool catalog (GPT parity)

The MCP tools are registered with the same names as GPT action operationIds:

• get_me
• get_brand_voice
• get_recent_notes
• get_ai_context
• post_notes
• post_notes_write
• get_repo_targets
• get_posts
• post_posts
• get_posts_by_id
• patch_posts_by_id
• delete_posts_by_id
• post_posts_by_id_publish
• post_posts_by_id_hero
• get_tweets
• post_tweets
• post_tweets_campaign
• get_tweets_by_id
• patch_tweets_by_id
• delete_tweets_by_id
• post_tweets_by_id_post
• post_tweets_by_id_schedule
• post_tweets_search
• post_tweets_reply
• get_x_accounts
• post_reservoir_ingest

Required fields for common write tools

• post_posts:
  • required: domain or site_id, title, content
• post_notes:
  • required: domain or site_id
  • and one of: content_markdown, transcript, or conversation
• post_notes_write:
  • required: domain or site_id, target_id, markdown_content
• post_tweets:
  • required: domain or site_id
  • and one of: text or thread

If a required field is missing, MCP returns INVALID_ARGUMENTS with field-level details.

13. Safety model

Publish/delete/schedule-sensitive tools use explicit confirmations via strict input schema checks:

• confirm: true is required for publish operations.
• Draft creation tools do not publish content.
• Idempotency keys are added for publish/schedule calls where feasible.

14. Known assumptions / TODOs

Input schemas for parity tools are permissive by design (passthrough) so they can track OpenAPI changes with fewer breaks. If you tighten request validation, update both MCP and OpenAPI together.