MoodTrue logo MoodTrue Developers

Model Context Protocol

MoodTrue MCP

Technical reference for connecting MCP-compatible clients to MoodTrue account, mood, social, usage, and playlist capabilities.

Server URLhttps://mcp.moodtrue.com/mcp
Client configuration OAuth metadata

Connection

Client configuration

Configure the remote server URL in a client that supports Streamable HTTP and OAuth authorization. Available tools are determined by the scopes approved during authorization.

  1. Enter the server URL

    Add https://mcp.moodtrue.com/mcp as a remote MCP server.

  2. Authorize MoodTrue

    Sign in to MoodTrue and review the requested permissions.

  3. Load tools

    The client calls tools/list and receives only tools covered by approved scopes.

  4. Confirm account changes

    Review write and destructive actions before they are sent.

Remote MCP configuration
{
  "mcpServers": {
    "moodtrue": {
      "url": "https://mcp.moodtrue.com/mcp"
    }
  }
}

Transport

Streamable HTTP and JSON-RPC

The server accepts authenticated JSON-RPC 2.0 requests over HTTP POST. It supports protocol negotiation, health checks, tool discovery, tool calls, initialization notifications, and cancellation notifications.

POST requests

Send initialize, ping, tools/list, and tools/call to the MCP server URL.

Protocol versions

Supports 2026-07-28, 2025-11-25, 2025-06-18, and 2025-03-26.

Initialize request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "your-client",
      "version": "1.0.0"
    }
  }
}
Protected resource/.well-known/oauth-protected-resource Authorization server/.well-known/oauth-authorization-server Service health/health

OAuth

User-controlled authorization

MoodTrue uses OAuth authorization code flow with PKCE. Access tokens are short-lived, refresh tokens rotate on use, and revoking a grant disables its linked developer access.

Discovery

The client reads protected-resource and authorization-server metadata.

Consent

The user signs in and approves explicit scopes.

Code exchange

The authorization code is exchanged with PKCE validation.

Token rotation

Refresh tokens rotate; detected reuse invalidates the grant family.

Tool reference

Available tools

Read tools are marked read-only. Follow operations change relationship state, while unfollow and playlist deletion are marked destructive so compatible clients can request additional confirmation.

Account

Account identity, profile, and API consumption.

get_my_account

Get my account

Returns basic information for the authenticated account.

account:read
get_my_profile

Get my profile

Returns profile, subscription, connection, and developer information.

account:read
get_api_usage

Get API usage

Returns current usage and rate-limit windows.

usage:read

Moods

Current mood, history, and statistics.

get_current_mood

Get current mood

Returns the authenticated user's analyzed mood and translations.

mood:read
get_mood_history

Get mood history

Returns paginated history with optional date filters.

mood:read
get_mood_statistics

Get mood statistics

Returns mood statistics for a selected period.

mood:read

Social

Privacy-aware profiles, posts, moods, and relationships.

get_user_profile

Get user profile

Returns a visible profile while enforcing privacy and block rules.

social:read
get_user_posts

Get user posts

Returns visible posts with cursor pagination.

social:read
get_user_mood

Get user mood

Returns mood activity when the requester is allowed to view it.

social:read
get_user_followers

Get user followers

Returns a privacy-filtered followers list.

social:read
get_user_following

Get user following

Returns a privacy-filtered following list.

social:read
follow_user

Follow user

Follows a public account as the authenticated user.

social:write
unfollow_user

Unfollow user

Removes the authenticated user's follow relationship.

social:write

Playlists

Owned MoodTrue playlists and tracks.

list_playlists

List playlists

Returns active playlists owned by the authenticated user.

playlists:read
get_playlist

Get playlist

Returns one owned playlist and its tracks.

playlists:read
delete_playlist

Delete playlist

Soft-deletes one MoodTrue playlist and its track records.

playlists:write
Tool call
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_current_mood",
    "arguments": {}
  }
}

Permissions

OAuth scopes

account:read

Read the connected account and profile.

usage:read

Read API usage and rate-limit windows.

mood:read

Read current mood, history, and statistics.

social:read

Read privacy-filtered social information.

social:write

Follow or unfollow accounts.

playlists:read

Read owned playlists and tracks.

playlists:write

Delete owned MoodTrue playlists.

offline_access

Allow rotating refresh tokens.

Errors

Protocol and authorization errors

CodeMeaning
401Access token is missing, expired, invalid, or revoked.
429The MCP request rate limit has been reached.
-32700The JSON-RPC request body could not be parsed.
-32600The JSON-RPC request structure is invalid.
-32601The requested protocol method does not exist.