Eden MCP API

openapi: 3.2.0
info:
  title: Eden MCP API
  version: 1.0.0
  summary: 'Eden''s public API for AI agents: a hosted MCP server for social research, analytics, boards, notes, and post scheduling.'
  description: 'Eden''s agent API is a hosted MCP (Model Context Protocol) server. Agents speak JSON-RPC 2.0 over Streamable HTTP to `POST https://mcp.eden.so/mcp` and get 113 tools (namespaced `eden_*`) covering outlier research across X, LinkedIn, Instagram, TikTok, YouTube, and Substack, private analytics, boards and notes, and scheduling/publishing.


    **Connect (MCP clients):** add a remote MCP server at `https://mcp.eden.so/mcp`. Claude Code: `claude mcp add --transport http eden https://mcp.eden.so/mcp`. Claude.ai/Desktop: Settings → Connectors → Add custom connector. Auth is OAuth 2.0 (authorization code + PKCE, dynamic client registration per RFC 7591, discovery per RFC 8414/9728).


    **Connect (plain HTTP, e.g. n8n/Zapier/Make):** create an API key in Eden under Settings → API and send it as `Authorization: Bearer eden_pat_…` on every request.


    **REST, no MCP client:** every tool also runs as `POST https://mcp.eden.so/v1/tools/` with its arguments as the JSON body (spec: https://mcp.eden.so/v1/openapi.json). The store API (sales, customers, products, email list, webhooks) has its own spec: https://api.eden.so/store-app/v1/openapi.json.


    **Tool errors:** tools return structured JSON. Failures are `{ ok: false, status, message }` — `status` says whether to fix input (`invalid`), reconnect (`auth-expired`), or surface to the user. Never retry an `invalid` payload unchanged.


    The full tool catalog is enumerated under the top-level `x-mcp` extension, and in human/agent-readable form at https://eden.so/llms-full.txt.'
  contact:
    name: Eden
    url: https://eden.so/help/
  termsOfService: https://eden.so/terms/
servers:
- url: https://mcp.eden.so
  description: Eden hosted MCP server
tags:
- name: MCP
paths:
  /mcp:
    post:
      operationId: mcp
      summary: MCP endpoint (JSON-RPC 2.0 over Streamable HTTP)
      description: 'The single MCP endpoint. Standard MCP methods apply: `initialize`, `tools/list`, `tools/call`. The server runs stateless — no `mcp-session-id` is issued and every request must carry `Authorization: Bearer ` (an OAuth access token or an `eden_pat_…` personal access token). Write-marked tools require a write-scoped token.'
      security:
      - oauth:
        - read
      - oauth:
        - read
        - write
      - personalAccessToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
      responses:
        '200':
          description: JSON-RPC response. Tool-level failures still return 200 — check the `ok` field of tool results (see ToolFailure).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '401':
          description: 'Missing or invalid bearer token. Carries `WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://mcp.eden.so/.well-known/oauth-protected-resource"` and a JSON-RPC error body with code -32001.'
        '429':
          description: Rate limited (per bearer token). Honor the `Retry-After` header; the body is a JSON-RPC error with code -32000.
      tags:
      - MCP
components:
  schemas:
    JsonRpcResponse:
      type: object
      required:
      - jsonrpc
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          type:
          - string
          - number
          - 'null'
        result:
          type: object
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
    JsonRpcRequest:
      type: object
      required:
      - jsonrpc
      - method
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          type:
          - string
          - number
        method:
          type: string
          description: MCP method, e.g. `initialize`, `tools/list`, `tools/call`.
        params:
          type: object
          description: 'For `tools/call`: `{ name, arguments }` where `name` is one of the tools listed in the top-level `x-mcp.tools`.'
  securitySchemes:
    oauth:
      type: oauth2
      description: OAuth 2.0 with PKCE. Clients self-register via dynamic client registration (RFC 7591) at POST https://oauth.eden.so/oauth/register. Access tokens expire after 1 hour; use the refresh token.
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.eden.so/oauth/authorize
          tokenUrl: https://oauth.eden.so/oauth/token
          refreshUrl: https://oauth.eden.so/oauth/token
          scopes:
            read: Read-only access to workspace data, social research, and analytics
            write: Create and modify boards, notes, scheduled posts, and other workspace data
    personalAccessToken:
      type: http
      scheme: bearer
      bearerFormat: eden_pat_…
      description: 'Personal access token (API key) for non-OAuth clients (n8n, Zapier, Make, scripts). Created in Eden under Settings → API; shown once at creation. Sent exactly like an OAuth token: `Authorization: Bearer eden_pat_…`.'
externalDocs:
  description: 'Full agent reference: connection guide, skills, and the complete MCP tool catalog'
  url: https://eden.so/llms-full.txt
x-specs:
- name: Eden workspace API (every MCP tool as a REST call)
  url: https://mcp.eden.so/v1/openapi.json
- name: Eden store API
  url: https://api.eden.so/store-app/v1/openapi.json
x-mcp:
  transport: streamable-http
  endpoint: https://mcp.eden.so/mcp
  registryName: so.eden/eden
  toolCount: 113
  toolNames:
  - eden_list_workspaces
  - eden_list_workspace_items
  - eden_find_workspace_items
  - eden_search_workspace_items
  - eden_get_note_markdown
  - eden_read_media_card
  - eden_read_board
  - eden_read_table
  - eden_get_connections
  - eden_list_tags
  - eden_list_chats
  - eden_read_card
  - eden_search_highlights
  - eden_search_captures
  - eden_search_creators
  - eden_resolve_creator
  - eden_analyze_creator
  - eden_read_social_post
  - eden_following_overview
  - eden_analyze_list
  - eden_search_social_content
  - eden_study_top_titles
  - eden_search_ads
  - eden_get_brand_ads
  - eden_get_brand_list_ads
  - eden_save_brands_to_list
  - eden_remove_brands_from_list
  - eden_save_creators_to_list
  - eden_create_board
  - eden_connect_items
  - eden_rename_board
  - eden_trash_board
  - eden_trash_item
  - eden_create_note
  - eden_patch_note
  - eden_update_note
  - eden_create_sticky_note
  - eden_rename_note
  - eden_append_to_note
  - eden_save_links_to_board
  - eden_save_posts_to_board
  - eden_save_posts_to_library
  - eden_save_ads_to_board
  - eden_save_items_to_board
  - eden_reorder_board
  - eden_add_media_to_board
  - eden_prepare_board_media_upload
  - eden_create_table
  - eden_add_table_rows
  - eden_update_table_rows
  - eden_update_table
  - eden_update_item_tags
  - eden_set_item_note
  - eden_list_schedules
  - eden_update_schedule
  - eden_list_scheduled_posts
  - eden_search_instagram_music
  - eden_prepare_scheduling_media_upload
  - eden_scheduling_media_multipart
  - eden_upload_scheduling_media
  - eden_import_scheduling_media
  - eden_create_scheduling_draft
  - eden_schedule_post
  - eden_publish_post_now
  - eden_update_scheduled_post
  - eden_schedule_drafts
  - eden_cancel_scheduled_post
  - eden_list_routines
  - eden_create_routine
  - eden_update_routine
  - eden_get_analytics
  - eden_list_analytics_posts
  - eden_connect_social_accounts
  - eden_list_auto_dm_rules
  - eden_create_auto_dm_automation
  - eden_update_auto_dm_automation
  - eden_delete_auto_dm_automation
  - eden_study_top_carousels
  - eden_list_custom_ai
  - eden_get_custom_ai
  - eden_create_custom_ai
  - eden_update_custom_ai
  - eden_manage_custom_ai_sources
  - eden_delete_custom_ai
  - eden_get_custom_ai_builder_guide
  - eden_read_custom_ai_knowledge
  - eden_search_custom_ai_knowledge
  - eden_ask_custom_ai
  - eden_get_custom_ai_answer
  - eden_list_skills
  - eden_get_skill
  - eden_export_skill
  - eden_import_skill
  - eden_import_product_reviews
  - eden_get_seller_overview
  - eden_list_stores
  - eden_get_custom_ai_product
  - eden_save_custom_ai_product
  - eden_publish_custom_ai_product
  - eden_get_bundle
  - eden_save_bundle
  - eden_organize_custom_ai_knowledge
  - eden_list_customers
  - eden_get_customer
  - eden_manage_customer_access
  - eden_import_customers
  - eden_manage_cohorts
  - eden_manage_coaching
  - eden_manage_content_links
  - eden_manage_affiliates
  - eden_manage_sales
  - eden_manage_store_emails
  - eden_manage_calendar
  - eden_manage_lesson_questions
  - eden_manage_forms
  - eden_update_creator_page
  tools:
  - name: eden_list_workspaces
    title: List workspaces
    group: Workspace
    write: false
  - name: eden_list_workspace_items
    title: List workspace items
    group: Workspace
    write: false
  - name: eden_find_workspace_items
    title: Find workspace items (semantic)
    group: Workspace
    write: false
  - name: eden_search_workspace_items
    title: Search workspace items
    group: Workspace
    write: false
  - name: eden_get_note_markdown
    title: Read note markdown
    group: Workspace
    write: false
  - name: eden_read_media_card
    title: Read media card content
    group: Workspace
    write: false
  - name: eden_read_board
    title: Read board contents
    group: Workspace
    write: false
  - name: eden_read_table
    title: Read table rows
    group: Workspace
    write: false
  - name: eden_get_connections
    title: Get item connections
    group: Workspace
    write: false
  - name: eden_list_tags
    title: List workspace tags
    group: Workspace
    write: false
  - name: eden_list_chats
    title: List chats
    group: Workspace
    write: false
  - name: eden_read_card
    title: Moved to eden_read_social_post
    group: Social intelligence
    write: false
    deprecated: true
    aliasOf: eden_read_social_post
  - name: eden_search_highlights
    title: Search highlights
    group: Highlights & captures
    write: false
  - name: eden_search_captures
    title: Search captures
    group: Highlights & captures
    write: false
  - name: eden_search_creators
    title: Search creators
    group: Social intelligence
    write: false
  - name: eden_resolve_creator
    title: Resolve creator
    group: Social intelligence
    write: false
  - name: eden_analyze_creator
    title: Analyze creator
    group: Social intelligence
    write: false
  - name: eden_read_social_post
    title: Read social post
    group: Social intelligence
    write: false
  - name: eden_following_overview
    title: List followed creators
    group: Social intelligence
    write: false
  - name: eden_analyze_list
    title: Analyze creator list
    group: Social intelligence
    write: false
  - name: eden_search_social_content
    title: Search social content
    group: Social intelligence
    write: false
  - name: eden_study_top_titles
    title: Study top titles
    group: Social intelligence
    write: false
  - name: eden_search_ads
    title: Search ads
    group: Social intelligence
    write: false
  - name: eden_get_brand_ads
    title: Get brand ads
    group: Social intelligence
    write: false
  - name: eden_get_brand_list_ads
    title: Get brand-list ads
    group: Social intelligence
    write: false
  - name: eden_save_brands_to_list
    title: Save brands to list
    group: Social intelligence
    write: true
  - name: eden_remove_brands_from_list
    title: Remove brands from list
    group: Social intelligence
    write: true
  - name: eden_save_creators_to_list
    title: Save creators to list
    group: Social intelligence
    write: true
  - name: eden_create_board
    title: Create board
    group: Boards & documents
    write: true
  - name: eden_connect_items
    title: Connect items
    group: Boards & documents
    write: true
  - name: eden_rename_board
    title: Rename board
    group: Boards & documents
    write: true
  - name: eden_trash_board
    title: Trash board
    group: Boards & documents
    write: true
  - name: eden_trash_item
    title: Trash item
    group: Boards & documents
    write: true
  - name: eden_create_note
    title: Create note
    group: Boards & documents
    write: true
  - name: eden_patch_note
    title: Edit passages in note
    group: Boards & documents
    write: true
  - name: eden_update_note
    title: Update note
    group: Boards & documents
    write: true
  - name: eden_create_sticky_note
    title: Moved to eden_create_note
    group: Boards & documents
    write: true
    deprecated: true
    aliasOf: eden_create_note
  - name: eden_rename_note
    title: Rename note
    group: Boards & documents
    write: true
  - name: eden_append_to_note
    title: Append to note
    group: Boards & documents
    write: true
  - name: eden_save_links_to_board
    title: Save links to board
    group: Boards & documents
    write: true
  - name: eden_save_posts_to_board
    title: Save social posts to board
    group: Boards & documents
    write: true
  - name: eden_save_posts_to_library
    title: Save social posts to Library
    group: Boards & documents
    write: true
  - name: eden_save_ads_to_board
    title: Save ads to board
    group: Boards & documents
    write: true
  - name: eden_save_items_to_board
    title: Save existing items to board
    group: Boards & documents
    write: true
  - name: eden_reorder_board
    title: Reorder board cards
    group: Boards & documents
    write: true
  - name: eden_add_media_to_board
    title: Add image or PDF to board
    group: Boards & documents
    write: true
  - name: eden_prepare_board_media_upload
    title: Prepare board image/PDF upload
    group: Boards & documents
    write: true
  - name: eden_create_table
    title: Create table
    group: Boards & documents
    write: true
  - name: eden_add_table_rows
    title: Add table rows
    group: Boards & documents
    write: true
  - name: eden_update_table_rows
    title: Update table rows
    group: Boards & documents
    write: true
  - name: eden_update_table
    title: Update table (columns/view)
    group: Boards & documents
    write: true
  - name: eden_update_item_tags
    title: Update item tags
    group: Boards & documents
    write: true
  - name: eden_set_item_note
    title: Set item note
    group: Boards & documents
    write: true
  - name: eden_list_schedules
    title: List schedules
    group: Scheduling
    write: false
  - name: eden_update_schedule
    title: Update schedule
    group: Scheduling
    write: true
  - name: eden_list_scheduled_posts
    title: List scheduled posts
    group: Scheduling
    write: false
  - name: eden_search_instagram_music
    title: Search Instagram music
    group: Scheduling
    write: false
  - name: eden_prepare_scheduling_media_upload
    title: Prepare scheduling media upload
    group: Scheduling
    write: true
  - name: eden_scheduling_media_multipart
    title: Multipart media upload step
    group: Scheduling
    write: true
  - name: eden_upload_scheduling_media
    title: Upload scheduling media
    group: Scheduling
    write: true
  - name: eden_import_scheduling_media
    title: Import scheduling media
    group: Scheduling
    write: true
  - name: eden_create_scheduling_draft
    title: Moved to eden_schedule_post
    group: Scheduling
    write: true
    deprecated: true
    aliasOf: eden_schedule_post
  - name: eden_schedule_post
    title: Schedule post
    group: Scheduling
    write: true
  - name: eden_publish_post_now
    title: Publish post now
    group: Scheduling
    write: true
  - name: eden_update_scheduled_post
    title: Update scheduled post
    group: Scheduling
    write: true
  - name: eden_schedule_drafts
    title: Schedule drafts
    group: Scheduling
    write: true
  - name: eden_cancel_scheduled_post
    title: Cancel scheduled post
    group: Scheduling
    write: true
  - name: eden_list_routines
    title: List routines
    group: Routines
    write: false
  - name: eden_create_routine
    title: Create routine
    group: Routines
    write: true
  - name: eden_update_routine
    title: Update routine
    group: Routines
    write: true
  - name: eden_get_analytics
    title: Get analytics digest
    group: Scheduling
    write: false
  - name: eden_list_analytics_posts
    title: List analytics posts
    group: Scheduling
    write: false
  - name: eden_connect_social_accounts
    title: Connect social accounts
    group: Scheduling
    write: true
  - name: eden_list_auto_dm_rules
    title: List Auto-DM automations
    group: Scheduling
    write: false
  - name: eden_create_auto_dm_automation
    title: Create Auto-DM automation
    group: Scheduling
    write: true
  - name: eden_update_auto_dm_automation
    title: Edit Auto-DM automation
    group: Scheduling
    write: true
  - name: eden_delete_auto_dm_automation
    title: Delete Auto-DM automation
    group: Scheduling
    write: true
  - name: eden_study_top_carousels
    title: Study top carousels
    group: Media
    write: false
  - name: eden_list_custom_ai
    title: List Custom AI
    group: Custom AI
    write: false
  - name: eden_get_custom_ai
    title: Get a Custom AI
    group: Custom AI
    write: false
  - name: eden_create_custom_ai
    title: Create Custom AI
    group: Custom AI
    write: true
  - name: eden_update_custom_ai
    title: Update Custom AI
    group: Custom AI
    write: true
  - name: eden_manage_custom_ai_sources
    title: Manage Custom AI knowledge
    group: Custom AI
    write: true
  - name: eden_delete_custom_ai
    title: Delete Custom AI
    group: Custom AI
    write: true
  - name: eden_get_custom_ai_builder_guide
    title: Custom AI builder guide
    group: Custom AI
    write: false
  - name: eden_read_custom_ai_knowledge
    title: Read Custom AI knowledge
    group: Custom AI
    write: false
  - name: eden_search_custom_ai_knowledge
    title: Search Custom AI knowledge
    group: Custom AI
    write: false
  - name: eden_ask_custom_ai
    title: Ask a Custom AI
    group: Custom AI
    write: true
  - name: eden_get_custom_ai_answer
    title: Get a Custom AI answer
    group: Custom AI
    write: false
  - name: eden_list_skills
    title: List skills
    group: Skills
    write: false
  - name: eden_get_skill
    title: Get skill
    group: Skills
    write: false
  - name: eden_export_skill
    title: Export skill
    group: Skills
    write: false
  - name: eden_import_skill
    title: Import skill
    group: Skills
    write: true
  - name: eden_import_product_reviews
    title: Import product reviews
    group: Store
    write: true
  - name: eden_get_seller_overview
    title: Get seller overview
    group: Store
    write: false
  - name: eden_list_stores
    title: List stores
    group: Store
    write: false
  - name: eden_get_custom_ai_product
    title: Get a Custom AI product
    group: Store
    write: false
  - name: eden_save_custom_ai_product
    title: Save a Custom AI product
    group: Store
    write: true
  - name: eden_publish_custom_ai_product
    title: Publish or unpublish a product
    group: Store
    write: true
  - name: eden_get_bundle
    title: Get a bundle
    group: Store
    write: false
  - name: eden_save_bundle
    title: Save a bundle
    group: Store
    write: true
  - name: eden_organize_custom_ai_knowledge
    title: Organize Custom AI knowledge
    group: Store
    write: true
  - name: eden_list_customers
    title: List customers
    group: Store
    write: false
  - name: eden_get_customer
    title: Get a customer
    group: Store
    write: false
  - name: eden_manage_customer_access
    title: Manage customer access
    group: Store
    write: true
  - name: eden_import_customers
    title: Import customers
    group: Store
    write: true
  - name: eden_manage_cohorts
    title: Manage cohorts
    group: Store
    write: true
  - name: eden_manage_coaching
    title: Manage coaching
    group: Store
    write: true
  - name: eden_manage_content_links
    title: Manage content links
    group: Store
    write: true
  - name: eden_manage_affiliates
    title: Manage affiliates
    group: Store
    write: true
  - name: eden_manage_sales
    title: Manage sales
    group: Store
    write: true
  - name: eden_manage_store_emails
    title: Manage store emails
    group: Store
    write: true
  - name: eden_manage_calendar
    title: Manage calendar
    group: Store
    write: true
  - name: eden_manage_lesson_questions
    title: Manage lesson questions
    group: Store
    write: true
  - name: eden_manage_forms
    title: Manage forms
    group: Store
    write: true
  - name: eden_update_creator_page
    title: Update creator page
    group: Store
    write: true