Charfeed MCP

Remote Model Context Protocol server that wraps the public Charfeed REST API. Connect from Claude, ChatGPT, Copilot, Cursor or any other MCP-compatible client and give an agent read access to your characters, posts, feeds, comments, subscriptions and notifications — gated by the same Identity Platform auth as the REST API.

Endpoint

Single HTTP endpoint, JSON-RPC over Streamable HTTP transport. Stateless: each request opens a fresh transport, so many clients can talk to the same URL simultaneously.

URL

https://mcp.charfeed.com

Send JSON-RPC 2.0 as POST to the root path. The server also responds to GET /health with {"status":"ok"}.

Authentication

Every MCP request is forwarded to the Charfeed REST API. To reach user-scoped tools (like charfeed_get_home_feed or charfeed_list_my_notifications), send an Identity Platform ID token on the MCP request:

Header

Authorization: Bearer <id-token>

Public tools (charfeed_check_handle, charfeed_list_featured_characters, charfeed_list_explore_characters) work without a token. Optional-auth tools return more data when a valid token is supplied (e.g. a subscriber sees tier-gated posts of a character).

Token lifetime is 1 hour. Your client is responsible for refreshing — the MCP server simply passes the header upstream.

Tools

Version 1 ships 13 read-only tools. Write operations (follow, like, comment, create character/post) are not yet exposed via MCP; use the REST API for those.

Tool	Auth	Upstream	Summary
`charfeed_get_me`	required	GET /v1/users/me	The authenticated user's profile, Stripe Connect state, content prefs.
`charfeed_update_my_profile`	required	PATCH /v1/users/me	Update displayName and/or bio on the authenticated user's profile (moderated).
`charfeed_change_my_handle`	required	PATCH /v1/users/me/handle	Change my handle (free, 30-day cooldown; previous handle reserved for 30 days).
`charfeed_list_my_characters`	required	GET /v1/users/me/characters	Characters owned by the authenticated user (full view).
`charfeed_list_my_follows`	required	GET /v1/users/me/follows	Characters the authenticated user follows, paginated.
`charfeed_list_my_reposts`	required	GET /v1/users/me/reposts	Posts the authenticated user has reposted, newest-first, paginated.
`charfeed_get_character_by_id`	optional	GET /v1/characters/by-id/:id	Full public character view by id.
`charfeed_get_character_by_handle`	optional	GET /v1/characters/by-handle/:handle	Full public character view by handle.
`charfeed_list_character_tiers`	optional	GET /v1/characters/:id/tiers	List a character's subscription tiers. Owners/admins can include inactive.
`charfeed_create_character`	required	POST /v1/characters	Create a new character (enters moderation with status=pending).
`charfeed_update_character`	required	PATCH /v1/characters/:id	Update mutable fields on a character (owner or admin). At least one field required.
`charfeed_get_post`	optional	GET /v1/posts/:id	Single post view with preview URLs, counters, rating and access level.
`charfeed_create_post`	required	POST /v1/posts	Publish a post on one of your characters. Requires completed media upload sessions.
`charfeed_update_post`	required	PATCH /v1/posts/:id	Update post fields (owner or admin). Supports soft-delete; featured is admin-only.
`charfeed_list_comments`	optional	GET /v1/posts/:postId/comments	Cursor-paginated non-deleted comments, newest-first.
`charfeed_create_comment`	required	POST /v1/posts/:postId/comments	Post a top-level comment or a reply (1000 chars max).
`charfeed_delete_comment`	required	DELETE /v1/posts/:postId/comments/:commentId	Soft-delete a comment (author, post owner, or admin).
`charfeed_list_featured_characters`	none	GET /v1/feeds/featured-characters	Curated featured characters from the home surface.
`charfeed_list_featured_posts`	none	GET /v1/feeds/featured-posts	Curated featured posts from the Explore hero carousel.
`charfeed_list_explore_characters`	none	GET /v1/feeds/explore/characters	Discovery feed: trending or recent, filterable by content type.
`charfeed_list_character_posts`	optional	GET /v1/feeds/characters/:characterId/posts	Posts from a character with access filtering based on the caller's subscriptions.
`charfeed_get_home_feed`	required	GET /v1/feeds/home	Personalized feed from characters the authenticated user follows.
`charfeed_get_like_status`	required	GET /v1/posts/:postId/likes/status	Whether the authenticated user has liked a given post.
`charfeed_like_post`	required	POST /v1/posts/:postId/likes	Like a post (idempotent).
`charfeed_unlike_post`	required	POST /v1/posts/:postId/likes/unlike	Remove a like from a post (idempotent).
`charfeed_get_repost_status`	required	GET /v1/posts/:postId/reposts/status	Whether the authenticated user has reposted a given post.
`charfeed_repost_post`	required	POST /v1/posts/:postId/reposts	Repost a post (idempotent).
`charfeed_unrepost_post`	required	POST /v1/posts/:postId/reposts/unrepost	Remove a repost from a post (idempotent).
`charfeed_follow_character`	required	POST /v1/follows	Follow a character (idempotent).
`charfeed_unfollow_character`	required	POST /v1/follows/unfollow	Unfollow a character (idempotent).
`charfeed_list_my_notifications`	required	GET /v1/notifications	The authenticated user's notifications with unread count.
`charfeed_mark_notification_read`	required	POST /v1/notifications/:id/read	Mark a single notification as read.
`charfeed_mark_all_notifications_read`	required	POST /v1/notifications/mark-all-read	Mark every unread notification as read; returns updated count.
`charfeed_list_my_subscriptions`	required	GET /v1/subscriptions/mine	The authenticated user's active paid subscriptions.

All list tools support cursor pagination (cursor, pageSize) and a response_format parameter ("markdown" default or "json").

Client setup

Claude Desktop / Claude Code

Add the server to your MCP configuration. Claude Desktop reads it from its app config; Claude Code reads it from ~/.claude/mcp.json or a project.mcp.json.

JSON

{
  "mcpServers": {
    "charfeed": {
      "url": "https://mcp.charfeed.com",
      "headers": {
        "Authorization": "Bearer <id-token>"
      }
    }
  }
}

ChatGPT

In the ChatGPT settings, open Connectors → Add connector → MCP serverand paste the URL. ChatGPT will prompt for the Identity Platform ID token as the connector's bearer credential.

URL

https://mcp.charfeed.com

Microsoft Copilot

Copilot (copilot.microsoft.com) accepts remote MCP servers via the connector/agent settings panel. Provide the URL above and paste a Identity Platform ID token as the bearer credential when asked.

URL

https://mcp.charfeed.com

Cursor / Windsurf / Zed / VS Code

All MCP-capable editors accept the same Streamable HTTP URL. The exact JSON shape varies, but the common fields are url and headers.Authorization:

JSON

{
  "mcpServers": {
    "charfeed": {
      "url": "https://mcp.charfeed.com",
      "headers": {
        "Authorization": "Bearer <id-token>"
      }
    }
  }
}

Quick sanity check

Without any tooling, curl the endpoint directly. A successful call returns the list of available tools.

curl

curl -sS -X POST https://mcp.charfeed.com \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

With a token, call an authenticated tool:

curl

curl -sS -X POST https://mcp.charfeed.com \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $ID_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"charfeed_get_home_feed","arguments":{"pageSize":5}}}'

CORS & origins

Browser-based MCP clients must call from an origin on the server's allowlist. The production allowlist is:

https://app.charfeed.com
https://claude.ai
https://chatgpt.com
https://copilot.microsoft.com

Requests from other origins receive 403. Desktop and CLI clients (Claude Desktop, Claude Code CLI, Cursor, Windsurf, Zed, VS Code) don't send an Origin header and pass through without CORS handling.

Troubleshooting

401 Unauthorized: Missing, malformed or expired Identity Platform ID token. Refresh the token in your client and try again.
403 Forbidden (from the MCP server, not upstream): Your Origin is not in the allowlist. If you're a browser-based client, ask to be added; desktop and CLI clients should not hit this.
403 Forbidden (from upstream): You're authenticated but the current user cannot access the resource (paywall, ownership or moderation). The tool's error message includes the reason.
404 Not Found: Unknown id or handle, or a private/suspended character. Double-check the identifier.
429 Too Many Requests: Upstream rate-limit. Reduce pageSize and/or back off.
Response truncated: Large list responses are capped at 25k characters. Use cursor pagination, narrow the query, or request response_format='json' for a more compact payload.