Nuelink MCP Server

Nuelink MCP Server (Cloudflare Workers)

Production remote MCP server for Nuelink APIs with OAuth 2.1 Authorization Code + PKCE.

Project Layout

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

Why tools can call Nuelink

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):

Required Nuelink callback allowlist

Production:

MCP Tool Catalog (from src/index.ts)

All tools return JSON as text content ({ content: [{ type: "text", text: JSON.stringify(...) }] }).

Shared response blocks

1) nuelink_validate_token

2) nuelink_get_me

3) nuelink_list_brands

4) nuelink_list_collections

5) nuelink_create_collection

6) nuelink_list_automations

Automation fields include:

7) nuelink_create_automation

8) nuelink_list_media

9) nuelink_list_channels

Channel shape:

10) nuelink_upload_file

11) nuelink_list_posts

Post fields include:

12) nuelink_create_post

Validation rules enforced by schema:

Example prompts follow the same publishing default:

13) nuelink_get_schedule

14) nuelink_list_brand_posts

15) nuelink_update_post

16) nuelink_move_posts

17) nuelink_delete_post

18) nuelink_list_published_posts

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

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:

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:

The OAuth provider will call /authorize with the correct OAuth request context.

To bypass OAuth with a direct Nuelink API key, connect to:

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:

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:

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.