LinkDR MCP Admin MCP API

openapi: 3.2.0
info:
  contact:
    email: support@linkdr.com
    name: LinkDR support
    url: https://linkdr.com/contact
  description: 'LinkDR is a managed backlink service: real publisher placements priced by Domain Rating (DR), ordered one-time or monthly, fulfilled in 3-4 weeks.


    Agents have three doors:


    1. Managed backlinks (no auth needed to plan): fetch https://linkdr.com/SKILL.md, plan the DR-tier mix from the budget, then send the user one https://linkdr.com/agent/checkout URL. The user logs in and pays in the browser; the user MCP can also charge a card already saved on the project, after the user confirms the quote.

    2. User MCP (any LinkDR account): https://linkdr.com/mcp over Streamable HTTP with OAuth 2.1. Your own projects, orders, outreach progress, live links, and AI answers, plus cache-first keyword SERPs and domain metrics. It can also add a site and its keywords, answer site approvals, quote and order links (a saved card is charged only after the user confirms; otherwise it returns the checkout link), and send feedback. Docs: https://linkdr.com/docs/mcp.

    3. Admin MCP (LinkDR admins only): https://linkdr.com/mcp/admin. The operator''s tools: every order and project, publisher outreach, customer emails, guest posts, and research with contacts. Other accounts complete OAuth and receive 403. Docs: https://linkdr.com/docs/admin.


    Machine-readable resources: this spec (https://linkdr.com/openapi.json), agent instructions (https://linkdr.com/llms.txt), the checkout skill (https://linkdr.com/SKILL.md), and docs (https://linkdr.com/docs).'
  termsOfService: https://linkdr.com/terms
  title: LinkDR Admin MCP API
  version: 1.0.0
servers:
- description: Production
  url: https://linkdr.com
tags:
- description: 'Operator tools for LinkDR admins: orders, projects, publisher outreach, and customer emails.'
  name: Admin MCP
paths:
  /mcp/admin:
    post:
      description: 'Model Context Protocol endpoint over Streamable HTTP (JSON-RPC 2.0; POST messages, optional SSE streams).


        Admin MCP for LinkDR admins: orders, projects, customers, publisher outreach, customer emails (preview first), guest posts, and research with contacts. Tool catalog: https://linkdr.com/docs/admin.


        Auth: OAuth 2.1 via Better Auth. Discover https://linkdr.com/.well-known/oauth-protected-resource/mcp/admin and /.well-known/oauth-authorization-server first; unauthenticated requests receive 401 with WWW-Authenticate. Dynamic client registration is supported. The signed-in account must have the admin role; other accounts receive 403 FORBIDDEN on every call. Rate limit: 120 requests/hour per user (429 with Retry-After).'
      operationId: mcpAdminStreamableHttp
      requestBody:
        description: JSON-RPC 2.0 request
        content:
          application/json:
            schema:
              description: A single MCP JSON-RPC 2.0 message (initialize, tools/list, tools/call, ...)
              properties:
                id:
                  type:
                  - integer
                  - string
                jsonrpc:
                  const: '2.0'
                  type: string
                method:
                  examples:
                  - initialize
                  - tools/list
                  - tools/call
                  type: string
                params:
                  type: object
              required:
              - jsonrpc
              - method
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
            text/event-stream:
              schema:
                type: string
          description: JSON-RPC result (or SSE stream for requests that opt in)
        '400':
          description: Malformed JSON-RPC message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or expired OAuth token; carries WWW-Authenticate pointing at the protected resource metadata
        '403':
          description: Origin not allowed, banned account, or (admin server) account lacks the admin role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: MCP disabled via MCP_DATA_ENABLED=false
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Hourly rate limit exceeded; see Retry-After
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - McpOAuth:
        - openid
        - email
      summary: Admin MCP server (Streamable HTTP)
      tags:
      - Admin MCP
components:
  schemas:
    Error:
      description: Structured error returned by all /api and /rpc failures. Agents should read code and hint.
      properties:
        error:
          properties:
            code:
              description: Stable machine-readable code.
              enum:
              - BAD_REQUEST
              - NOT_FOUND
              - METHOD_NOT_ALLOWED
              - UNAUTHORIZED
              - FORBIDDEN
              - RATE_LIMIT_EXCEEDED
              - INTERNAL_ERROR
              type: string
            hint:
              description: Resolution hint for the caller.
              type: string
            message:
              description: Human-readable summary.
              type: string
            status:
              description: HTTP status repeated in the body.
              type: integer
          required:
          - code
          - message
          - status
          type: object
      type: object
    JsonRpcResponse:
      description: MCP JSON-RPC 2.0 response envelope.
      properties:
        error:
          type: object
        id:
          type:
          - integer
          - string
        jsonrpc:
          const: '2.0'
          type: string
        result:
          type: object
      required:
      - jsonrpc
      type: object
  securitySchemes:
    McpOAuth:
      description: 'OAuth 2.1 authorization-code flow with PKCE (required) for both MCP servers. Authorization server metadata: https://linkdr.com/.well-known/oauth-authorization-server. Dynamic client registration is accepted. Each server is its own protected resource (https://linkdr.com/mcp and https://linkdr.com/mcp/admin), so a token is audience-bound to one of them. The admin server also requires the admin role on the LinkDR account.'
      flows:
        authorizationCode:
          authorizationUrl: /api/auth/oauth2/authorize
          refreshUrl: /api/auth/oauth2/token
          scopes:
            email: Identify the account by email address during sign-in
            offline_access: Receive a refresh token so long-running agent sessions stay connected until revoked
            openid: Sign in with a LinkDR account
            profile: Read the account display name
          tokenUrl: /api/auth/oauth2/token
      type: oauth2
    SessionCookie:
      description: Dashboard session cookie (better-auth.session_token) issued by browser sign-in. Endpoints under this scheme serve the logged-in app and its rate limits; there is no header-token alternative yet.
      in: cookie
      name: better-auth.session_token
      type: apiKey