Nuelink MCP Server (Cloudflare Workers)
Production remote MCP server for Nuelink APIs with OAuth 2.1 Authorization Code + PKCE.
Project Layout
src/index.ts: MCP server + tool registration + Zod input/output schemassrc/app.ts: OAuth bridge routes (/authorize,/callback) and config validationsrc/oauth-refresh.ts: upstream Nuelink token rotation during MCP refresh grantssrc/utils.ts: shared HTML layout and homepage rendering helperscripts/oauth-acceptance.mjs: logged-in OAuth and MCP lifecycle acceptance runnerscripts/validate-registry.mjs: local Registry manifest consistency checksserver.json: canonical Official MCP Registry metadataicon.png: source Registry iconpublic/: deployed copies of the icon and README, served at/icon.pngand/README.mdserver/: local mock OAuth provider for end-to-end local testing
How Auth Works (app.ts + utils.ts)
This project uses Cloudflare @cloudflare/workers-oauth-provider as the MCP auth layer and bridges to Nuelink OAuth. It advertises and accepts Client ID Metadata Documents (CIMD), while retaining Dynamic Client Registration (DCR) for backward-compatible clients.
Route ownership
GET /insrc/app.ts- Renders a homepage using
homeContent()andlayout()fromsrc/utils.ts.
- Renders a homepage using
GET /authorizeinsrc/app.ts- Validates required OAuth env config (
resolveOAuthConfig). - Parses MCP auth request via
OAUTH_PROVIDER.parseAuthRequest. - Generates
state+ PKCE (code_verifier,code_challenge). - Stores transaction in
OAUTH_KVfor callback validation. - Redirects user to Nuelink authorize URL (
NUELINK_OAUTH_AUTHORIZE_URL).
- Validates required OAuth env config (
GET /callbackinsrc/app.ts- Validates
codeandstatequery params. - Loads + deletes state transaction from
OAUTH_KV. - Exchanges code for token at
NUELINK_OAUTH_TOKEN_URL. - Calls
OAUTH_PROVIDER.completeAuthorization(...). - Injects exchanged token into MCP props as
props.apiKey. - Redirects to MCP client callback URL returned by OAuth provider.
- Validates
GET /mcp?api_key=...or requests withx-api-key/x-nuelink-api-keyinsrc/index.ts- Calls
GET https://app.nuelink.com/api/public/v1/mewith the provided key. - If
/mesucceeds, stripsapi_keyfrom the request URL. - Removes the API-key auth material from the forwarded request and sets
ctx.props.apiKey. - Skips the OAuth redirect flow entirely for that request.
- Calls
Why tools can call Nuelink
- In
src/index.ts, tools usethis.props.apiKey. - That value is set in
src/app.tsafter OAuth token exchange. - Each API call sends
Authorization: Bearer ${apiKey}.
Tool metadata and safety
All 24 tools publish a human-readable title and description, an output schema, and the four MCP safety annotations: readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The annotation object also repeats the human-readable title for clients that read annotations.title. Successful calls return both text content and schema-validated structuredContent; failed calls are marked with isError.
Read tools are marked read-only and idempotent. Create, upload, and update tools are marked non-read-only and non-idempotent. openWorldHint: true marks tools whose effects can reach beyond the current account state, including channel assignments, queue-slot changes, automation activation, moving posts to new destinations, and post publishing or scheduling. Destructive operations include those changes, automation creation, post updates that can resume publishing, and permanent post deletion.
Tool names are a stable public contract. The lifecycle suite asserts the exact 24-name list so an accidental rename fails CI.
Session termination
Authenticated DELETE /mcp requests require mcp-session-id, resolve the same Durable Object with the authenticated props, destroy its persisted session state, and return HTTP 204. Unknown sessions return 404; missing session IDs return 400. Unexpected Durable Object failures are returned as a generic JSON-RPC 500 with a redacted structured log event rather than an uncaught Worker exception.
Environment Configuration
Required secrets
wrangler secret put NUELINK_OAUTH_CLIENT_ID
wrangler secret put NUELINK_OAUTH_CLIENT_SECRET
Runtime vars
Configured in wrangler.jsonc (and overrideable via .dev.vars locally):
NUELINK_OAUTH_AUTHORIZE_URLdefault:https://app.nuelink.com/mcp/authorizeNUELINK_OAUTH_TOKEN_URLdefault:https://app.nuelink.com/mcp/oauth/tokenMCP_CALLBACK_URLdefault:https://mcp.nuelink.com/callbackNUELINK_OAUTH_SCOPEdefault:full_access
Required Nuelink callback allowlist
Production:
https://mcp.nuelink.com/callback
MCP Tool Catalog (from src/index.ts)
All tools return JSON as text content ({ content: [{ type: "text", text: JSON.stringify(...) }] }).
Shared response blocks
Error shape
status?: stringmessage: stringerrors: Record<string, string | string[]>
Pagination shape
currentPage: numberperPage: numbertotal: numberlastPage: numbernextPageUrl: string | nullprevPageUrl: string | null
1) nuelink_validate_token
Input schema
{}
Calls
GET /auth, an alias ofGET /me, and returns the authenticated profile.
2) nuelink_get_me
Input schema
{}
Output schema
status: stringdata: { id: string, name: string, joinedAt: string, timezone: string | null }
3) nuelink_list_brands
Input schema
page?: integer(minimum 1; default 1)perPage?: integer(1..100; default 25)
Output schema
status: stringdata: Array<{ id: number, title: string, description: string | null, timezone: string | null, queueStatus: "ACTIVE" | "PAUSED", createdAt: string, updatedAt: string }>pagination
4) nuelink_list_collections
Input schema
brandId: integer(minimum 1)page?: integer(minimum 1; default 1)perPage?: integer(1..100; default 25)
Output schema
status: stringdata: Collection[], including status, evergreen configuration, timezone, channels, queue slots, and post countspagination
5) nuelink_create_collection
Input schema
brandId: integer(minimum 1)title: string (max 255)description?: string | nullmaxRepublish?: number | null(int, min 0)channels?: number[](positive ints)queues?: string[]formatMon 12:34
Output schema
status: stringdata: Collection, including status, evergreen configuration, timezone, channels, and queue slots
6) nuelink_list_automations
Input schema
brandId: integer(minimum 1)page?: integer(minimum 1; default 1)perPage?: integer(1..100; default 25)
Output schema
status: stringdata: Automation[]pagination
Automation fields include:
id: numbername, type, feedUrl, createdAt, updatedAt: stringtitle, caption, importAsType: string | nullstatus: stringcollectionId, lastRun: numberaddPostsAsDraft: booleanandrefreshRate: number | null(hours between checks: 1, 6, 12, or 24)runCount: number | null
7) nuelink_create_automation
Input schema
brandId: integer(minimum 1)name: string (max 255)collectionId: number(int >= 1)type: one ofYOUTUBE | RSS | ATOM | MEDIUM | SHOPIFY | WORDPRESS | WOOCOMMERCE | ETSY | GHOST | SUBSTACK | ANCHOR | TRANSISTOR | CAPTIVATE | SOUNDCLOUD | BLOGGER | WIX | SQUARESPACEBLOG | SQUARESPACESHOP | WEEBLY | TUMBLR | SHOPIFY2 | WOOCOMMERCE2 | PRESTASHOP | BUZZSPROUT | RSSCOM | CASTOS | PODCASTCO
feedUrl: string (url)importAsType: "LINK" | "IMAGE" | "VIDEO" | "CAROUSEL"title?: string | null (max 255)caption?: string | null (max 255)loadOldPosts?: boolean | nulladdPostsAsDraft?: boolean | nullrefreshRate?: 24 | 12 | 6 | 1 | null
Output schema
status: stringdata: Automation
8) nuelink_list_media
Input schema
brandId: number(int >= 1)type?: "IMAGE" | "VIDEO" | "GIF" | "APPLICATION" | "DOCUMENT" | "CSV"page?: integer(minimum 1; default 1)perPage?: integer(1..100; default 25)
Output schema
status: stringdata: Array<{ id: string, type: string, name: string, size: number, createdAt: string, updatedAt: string }>pagination
9) nuelink_list_channels
Input schema
brandId: integer(minimum 1)page?: integer(minimum 1; default 1)perPage?: integer(1..100; default 25)
Output schema
status: stringdata: Channel[]pagination
Channel shape:
id: numbername: stringstatus: "ACTIVE" | "INACTIVE"type: stringcreatedAt: stringupdatedAt: string
10) nuelink_upload_file
Input schema
brandId: integer(minimum 1)fileName: stringfileContent: string(base64; JPEG, PNG, BMP, MP4, MOV, or PDF; maximum 100 MiB)
Output schema
status: stringdata: { id: string, type: string, size: number }
11) nuelink_list_posts
Input schema
brandId: integer(minimum 1)collectionId: integer(minimum 1)page?: integer(minimum 1; default 1)perPage?: integer(1..100; default 25)view?: "QUEUE" | "SCHEDULED" | "DRAFT" | "PUBLISHED"status?: "PENDING" | "DRAFT" | "PUBLISHED"(PENDINGincludes queued and scheduled posts; combine withvieworpostingTypeto distinguish them)postType?: "TEXT" | "IMAGE" | "VIDEO" | "MULTIMEDIA" | "SHORT" | "DOCUMENT" | "THREAD" | "SLIDES" | "REEL" | "TIKTOK" | "STORY" | "POLL" | "ENGAGE_COMMENT"postingType?: "NOW" | "SCHEDULE" | "QUEUE" | "DRAFT"createdFrom?, createdTo?: string(YYYY-MM-DD HH:mm:ss, UTC;createdTomust not precedecreatedFrom)sortBy?: "id" | "title" | "post_date" | "created_at" | "updated_at"sortOrder?: "asc" | "desc"
Output schema
status: stringdata: Post[]pagination
Post fields include:
id, collectionId: numberchannels: ChannelSummary[](effective destinations: targeted channels when set, otherwise the collection's assigned channels; unavailable channels and Pinterest account-container records are omitted)title, body, postDate: string | nullpostType, postingType, status, createdAt, updatedAt: stringmedia: Array<{ id: string }>poll?: { caption, question, explanation: string | null, options: string[] | null, period: "1d" | "3d" | "7d" | null, correctOptionIndex?: number | null }
12) nuelink_create_post
- Input schema
brandId: number(int >= 1)collectionId: number(int >= 1)title?: string | null (max 255)caption?: string | null (1..3000)poll?: { question, options[2..4], correctOptionIndex?, explanation?, period } | null; a non-null poll requiresquestion, 2 to 4options, andperiod(1d,3d, or7d)alt?: string | null (max 255)link?: string | null (url, max 1000)autoThreadText?: boolean | null(defaults totrue; setfalseto disable automatic text splitting)publishMode?: "IMMEDIATE" | "SCHEDULE" | "QUEUE" | "DRAFT"(optional in this MCP tool; defaults toDRAFT. The REST Public API request contract separately requires this field.)scheduledAt?: string | nullformatYYYY-MM-DD HH:mm:ssin the brand's local timezone; confirm an absolute time at least 10 minutes ahead before executionmedia?: Array<{ id?: string, url?: string }> | nullexactly one ofidorurlper item; supplying both is invalid regardless of their typespostAsStory?: boolean | nullplatforms?: { instagram?: { collab?, location?, trialReel?, shareToFeed? }, facebook?: { location? }, tiktok?: { sendToInbox?, autoAddMusic? }, youtube?: { tags?, playlists? }, googlemybusiness?: { uploadToPhotosSection? } }comment?: { delay: number, comment: string } | nullwheredelayis the number of minutes after publishing before the comment is posted (minimum1)
Validation rules enforced by schema:
captionis required whenpollis not provided.scheduledAtis required whenpublishModeisSCHEDULE.- Omitting
publishModecreates a draft; publishing modes must be selected explicitly. - A non-null poll must include its options; a question and period alone are invalid.
poll,comment, andplatformsacceptnull. Each platform entry and its optional fields acceptnullas declared in the tool schema.
Example prompts follow the same publishing default:
"Create a post with this caption" saves a
DRAFTwhen publishing intent is ambiguous."Queue this caption in Product Launches" explicitly selects
publishMode: "QUEUE"after resolving the brand, collection, and destination channels."Save this poll as a draft" requires a question, 2 to 4 options, and a supported period, and selects
publishMode: "DRAFT".Output schema
status: stringdata: { id: number, message: string }
13) nuelink_get_schedule
- Input:
brandId - Returns the brand timezone, queue status, and weekly queue slots grouped by day.
14) nuelink_list_brand_posts
- Input:
brandIdplus optional collection, view, lifecycle, type, date, sorting, and pagination filters. status: PENDINGincludes queued and scheduled posts; combine withvieworpostingTypeto distinguish them.- Returns the same paginated post shape as
nuelink_list_posts, across all brand collections. - Each post's
channelsshows its current effective destinations, including custom targets set in the dashboard.
15) nuelink_update_post
- Input:
brandId,postId, and at least one ofcaption,publishMode, orqueuePosition. captionedits a non-poll, unpublished post caption (1–3000 characters) without changing media.publishModeacceptsDRAFT,SCHEDULE, orQUEUE;scheduledAtis required only forSCHEDULE.- Returns the updated post.
16) nuelink_move_posts
- Input:
brandId,sourceCollectionId,destinationCollectionId, and 1–100 uniquepostIds. - Atomically moves posts between two distinct collections in the same brand. If any post is not in the source collection, none are moved.
- Returns
moved, both collection IDs, and the API success message.
17) nuelink_delete_post
- Input:
brandIdandpostId. - Permanently deletes the post and is marked with
destructiveHint: true. - Nuelink refuses the operation unless sensitive AI actions are enabled for the account.
18) nuelink_list_published_posts
- Input:
brandIdplus optional status, collection, channel, source post, post type, search, publication date, sorting, and pagination filters. statusdefaults toPUBLISHED; passFAILED,RETRYING,SKIPPED, orSENTseparately to inspect those outcomes.- Returns per-channel published results with likes, comments, shares, views, saves, engagement, clicks, impressions, and reach.
Representative Tool Examples
The examples below use MCP JSON-RPC style payloads.
Example 1: nuelink_get_me
Request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "nuelink_get_me",
"arguments": {}
}
}
Response body inside tool content (example):
{
"status": "success",
"data": {
"id": "usr_123",
"name": "Demo User",
"joinedAt": "2026-01-01T00:00:00Z",
"timezone": "UTC"
}
}
Example 2: nuelink_list_brands
Request:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "nuelink_list_brands",
"arguments": {
"page": 1,
"perPage": 10
}
}
}
Response body inside tool content (example):
{
"status": "success",
"data": [
{
"id": 11,
"title": "Brand A",
"description": "Main brand",
"timezone": "UTC",
"createdAt": "2026-01-10T10:00:00Z",
"updatedAt": "2026-02-01T10:00:00Z"
}
],
"pagination": {
"currentPage": 1,
"perPage": 10,
"total": 1,
"lastPage": 1,
"nextPageUrl": null,
"prevPageUrl": null
}
}
Example 3: nuelink_create_collection
Request:
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "nuelink_create_collection",
"arguments": {
"brandId": 11,
"title": "My Collection",
"description": "Posts for weekly publishing",
"maxRepublish": 2,
"channels": [101, 102],
"queues": ["Mon 08:00", "Wed 10:30"]
}
}
}
Response body inside tool content (example):
{
"status": "success",
"data": {
"id": 77,
"title": "My Collection",
"description": "Posts for weekly publishing",
"maxRepublish": 2,
"createdAt": "2026-07-17T00:00:00Z",
"updatedAt": "2026-07-17T00:00:00Z",
"channels": [{ "id": 101, "name": "Instagram", "status": "ACTIVE", "type": "INSTAGRAM" }],
"queues": [{ "id": 1, "date": "Mon 08:00", "status": "ACTIVE" }]
}
}
Example 4: nuelink_create_post (Scheduled)
Request:
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "nuelink_create_post",
"arguments": {
"brandId": 11,
"collectionId": 77,
"caption": "New product update.",
"publishMode": "SCHEDULE",
"scheduledAt": "BRAND_LOCAL_FUTURE_YYYY-MM-DD_HH:mm:ss",
"media": [{ "id": "media_123" }],
"comment": {
"delay": 5,
"comment": "Tell us what you think"
}
}
}
}
Response body inside tool content (example):
{
"status": "success",
"data": {
"id": 9001,
"message": "Post created successfully"
}
}
Example 5: Error format
{
"status": "error",
"message": "Validation failed.",
"errors": {
"scheduledAt": ["scheduledAt is required when publishMode is SCHEDULE."]
}
}
Example 6: nuelink_move_posts
Moving posts changes account state, so confirm the brand, both collection IDs, and every post ID before calling the tool. The operation is atomic: any post outside the source collection prevents all moves.
Request:
{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "nuelink_move_posts",
"arguments": {
"brandId": 11,
"sourceCollectionId": 77,
"destinationCollectionId": 81,
"postIds": [8801, 8802]
}
}
}
Response body inside tool content (example):
{
"status": "success",
"data": {
"moved": 2,
"sourceCollectionId": 77,
"destinationCollectionId": 81,
"message": "Post(s) moved successfully"
}
}
Collection and automation management tools
nuelink_update_collection: requiresbrandIdandcollectionId; accepts one or more oftitle,description,status(ACTIVE/PAUSED), andmaxRepublish.nuelink_add_collection_channelandnuelink_remove_collection_channel: requirebrandId,collectionId, andchannelId.nuelink_add_collection_queue_slot: requiresbrandId,collectionId, and a weeklydatesuch asMon 09:30in the brand timezone.nuelink_delete_collection_queue_slot: requiresbrandId,collectionId, andqueueId.nuelink_update_automation_status: requiresbrandId,automationId, andstatus(ACTIVE,PAUSED, orINACTIVE).
These tools update the connected account. Review the resolved IDs and requested changes before invocation.
Complete Invocation Reference
Every catalogued tool has a schema above; these minimal arguments examples
provide a copyable invocation starting point. Replace every numeric ID and
placeholder with a value resolved from the connected account. Mutating tools
must be explicitly confirmed immediately before invocation.
| Tool | Minimal arguments example |
|---|---|
nuelink_validate_token |
{} |
nuelink_get_me |
{} |
nuelink_list_brands |
{ "page": 1, "perPage": 25 } |
nuelink_list_collections |
{ "brandId": 11, "page": 1, "perPage": 25 } |
nuelink_create_collection |
{ "brandId": 11, "title": "Product updates" } |
nuelink_update_collection |
{ "brandId": 11, "collectionId": 77, "status": "PAUSED" } |
nuelink_add_collection_channel |
{ "brandId": 11, "collectionId": 77, "channelId": 501 } |
nuelink_remove_collection_channel |
{ "brandId": 11, "collectionId": 77, "channelId": 501 } |
nuelink_add_collection_queue_slot |
{ "brandId": 11, "collectionId": 77, "date": "Mon 09:30" } |
nuelink_delete_collection_queue_slot |
{ "brandId": 11, "collectionId": 77, "queueId": 911 } |
nuelink_list_automations |
{ "brandId": 11, "page": 1, "perPage": 25 } |
nuelink_create_automation |
{ "brandId": 11, "name": "Company blog", "collectionId": 77, "type": "RSS", "feedUrl": "https://example.com/feed.xml", "importAsType": "LINK" } |
nuelink_update_automation_status |
{ "brandId": 11, "automationId": 315, "status": "PAUSED" } |
nuelink_list_media |
{ "brandId": 11, "type": "IMAGE", "page": 1, "perPage": 25 } |
nuelink_list_channels |
{ "brandId": 11, "page": 1, "perPage": 25 } |
nuelink_upload_file |
{ "brandId": 11, "fileName": "launch.jpg", "fileContent": "BASE64_ENCODED_FILE_CONTENT" } |
nuelink_list_posts |
{ "brandId": 11, "collectionId": 77, "page": 1, "perPage": 25 } |
nuelink_get_schedule |
{ "brandId": 11 } |
nuelink_list_brand_posts |
{ "brandId": 11, "view": "SCHEDULED", "page": 1, "perPage": 25 } |
nuelink_update_post |
{ "brandId": 11, "postId": 8801, "caption": "Updated post text" } |
nuelink_move_posts |
{ "brandId": 11, "sourceCollectionId": 77, "destinationCollectionId": 81, "postIds": [8801] } |
nuelink_delete_post |
{ "brandId": 11, "postId": 8801 } |
nuelink_list_published_posts |
{ "brandId": 11, "status": "PUBLISHED", "page": 1, "perPage": 25 } |
nuelink_create_post |
{ "brandId": 11, "collectionId": 77, "caption": "Review this draft.", "publishMode": "DRAFT" } |
Local End-to-End Testing
This repo includes a local OAuth mock in server/.
1) Start mock OAuth server
cd server
npm start
Mock endpoints:
GET http://127.0.0.1:9797/mcp/authorizePOST http://127.0.0.1:9797/mcp/oauth/tokenGET http://127.0.0.1:9797/health
Token exchange returns DEMO_API_KEY.
2) Local env for worker
Create .dev.vars in repo root:
NUELINK_OAUTH_CLIENT_ID=LOCAL_DEMO_CLIENT
NUELINK_OAUTH_CLIENT_SECRET=LOCAL_DEMO_SECRET
NUELINK_OAUTH_AUTHORIZE_URL=http://127.0.0.1:9797/mcp/authorize
NUELINK_OAUTH_TOKEN_URL=http://127.0.0.1:9797/mcp/oauth/token
MCP_CALLBACK_URL=http://127.0.0.1:8787/callback
NUELINK_OAUTH_SCOPE=full_access
3) Start worker
npm run dev
npm run dev is pinned to port 8787 to match local callback URL.
4) Test through MCP client
Trigger auth from your MCP client against:
http://127.0.0.1:8787/mcp
The OAuth provider will call /authorize with the correct OAuth request context.
To bypass OAuth with a direct Nuelink API key, connect to:
http://127.0.0.1:8787/mcp?api_key=YOUR_KEY
The worker validates the key against /me before forwarding the MCP request.
5) Run the logged-in OAuth acceptance test
Run this against a deployed environment whose OAuth client callback configuration permits the dynamically registered localhost callback:
MCP_ACCEPTANCE_BASE_URL=https://mcp.nuelink.com npm run test:oauth-acceptance
On PowerShell:
$env:MCP_ACCEPTANCE_BASE_URL = "https://mcp.nuelink.com"
npm.cmd run test:oauth-acceptance
Open the printed authorization URL and approve access. The runner then verifies:
- OAuth discovery advertises CIMD support while retaining DCR fallback;
- consent and authorization-code exchange;
- rejection of an invalid PKCE verifier and acceptance of the correct verifier;
- MCP initialize,
tools/list,nuelink_get_me, and authenticated session termination; - refresh-token exchange, including rotation of the upstream Nuelink token;
- refresh-token revocation and HTTP
401rejection of the revoked grant.
The callback listener defaults to http://127.0.0.1:9789/callback. Set MCP_ACCEPTANCE_CALLBACK_PORT to use another local port.
Deploy
npm run deploy
Then connect clients to:
https://<your-domain>/mcp
For Claude Desktop / other remote MCP clients, always register the /mcp endpoint, not only the domain root.
OpenAI App Domain Verification
The verification token from the OpenAI submission portal is stored in
public/.well-known/openai-apps-challenge. If OpenAI issues a new token, update
that file before deploying. The file must contain only the exact token, without
JSON, quotes, or additional tokens. See the OpenAI domain verification requirements.
Cloudflare serves this static asset without OAuth at
https://mcp.nuelink.com/.well-known/openai-apps-challenge. The public/_headers
rule sets its content type to plain text and disables browser caching.
After deployment, check that this URL returns HTTP 200 with the exact token as its body, then select Verify Domain in the OpenAI submission portal.
Registry Metadata
The canonical Official MCP Registry manifest is server.json. Validate local invariants with:
npm run registry:validate
Before publishing, validate against the official publisher CLI and authenticate the nuelink.com namespace:
mcp-publisher validate server.json
mcp-publisher login dns --domain=nuelink.com --private-key="$MCP_REGISTRY_PRIVATE_KEY"
mcp-publisher publish server.json
Keep the private signing key out of the repository. The required DNS TXT record and the final publish action must be completed by a Nuelink domain administrator.