# Send an MCP message

Source: https://docs.musicnerd.net/api-reference/mcp/message

Send an MCP message

## POST /mcp

Full OpenAPI specification: https://docs.musicnerd.net/spec/mcp.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://docs.musicnerd.net/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Music Nerd API: MCP server",
    "version": "1.0.0",
    "description": "The Music Nerd MCP server over Streamable HTTP. Agents connect with OAuth, and the tools they get depend on who approved the connection: artist search and links for anyone signed in, link and ID-mapping writes for admins, and the team board for team members."
  },
  "servers": [
    {
      "url": "https://api.musicnerd.net",
      "description": "Production"
    },
    {
      "url": "https://musicnerd-api-staging.vercel.app",
      "description": "Staging (staging database)"
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "summary": "Send an MCP message",
        "description": "Sends a JSON-RPC 2.0 MCP message, or a batch, and streams the responses as server-sent events. Every request needs an OAuth access token. `tools/list` returns the tools this connection can use, with their input schemas.",
        "operationId": "postMcpMessage",
        "security": [
          {
            "mcpOAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "examples": {
                "initialize": {
                  "summary": "initialize",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {
                      "protocolVersion": "2025-06-18",
                      "capabilities": {},
                      "clientInfo": {
                        "name": "example-client",
                        "version": "1.0.0"
                      }
                    }
                  }
                },
                "toolsList": {
                  "summary": "tools/list",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 2,
                    "method": "tools/list"
                  }
                },
                "searchArtists": {
                  "summary": "tools/call search_artists",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 3,
                    "method": "tools/call",
                    "params": {
                      "name": "search_artists",
                      "arguments": {
                        "query": "Bio Ritmo",
                        "limit": 5
                      }
                    }
                  }
                },
                "setArtistLink": {
                  "summary": "tools/call set_artist_link (admins)",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 4,
                    "method": "tools/call",
                    "params": {
                      "name": "set_artist_link",
                      "arguments": {
                        "artistId": "aab92f80-f9e1-4299-aa33-7dd85c8de5d3",
                        "url": "https://instagram.com/bioritmomusic"
                      }
                    }
                  }
                },
                "reply": {
                  "summary": "tools/call reply (team members)",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 5,
                    "method": "tools/call",
                    "params": {
                      "name": "reply",
                      "arguments": {
                        "id": "msg_03dab9fa-322e-4fc5-9651-e3c9c7548036_1",
                        "text": "Preview checks pass."
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The responses, one `message` event per JSON-RPC response. A failed tool call is a result with `isError: true`.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "searchArtists": {
                    "summary": "search_artists result",
                    "value": "event: message\ndata: {\"jsonrpc\":\"2.0\",\"id\":3,\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"{\\n  \\\"artists\\\": [\\n    {\\n      \\\"id\\\": \\\"aab92f80-f9e1-4299-aa33-7dd85c8de5d3\\\",\\n      \\\"name\\\": \\\"Bio Ritmo\\\"\\n    }\\n  ],\\n  \\\"totalResults\\\": 1\\n}\"}]}}\n\n"
                  }
                }
              }
            }
          },
          "202": {
            "description": "The body held only notifications or responses (for example `notifications/initialized`); nothing to answer."
          },
          "400": {
            "description": "The body is not valid JSON or not a JSON-RPC message, or the `Mcp-Protocol-Version` header names an unsupported version.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcError"
                },
                "example": {
                  "jsonrpc": "2.0",
                  "error": {
                    "code": -32700,
                    "message": "Parse error: Invalid JSON"
                  },
                  "id": null
                }
              }
            }
          },
          "401": {
            "description": "No token, or an expired, revoked or unknown one. The `WWW-Authenticate` header points to the resource metadata, where an MCP client finds how to sign in.",
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "example": "Bearer resource_metadata=\"https://api.musicnerd.net/.well-known/oauth-protected-resource/mcp\""
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcError"
                },
                "example": {
                  "jsonrpc": "2.0",
                  "error": {
                    "code": -32000,
                    "message": "Unauthorized"
                  },
                  "id": null
                }
              }
            }
          },
          "406": {
            "description": "`Accept` does not list both `application/json` and `text/event-stream`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcError"
                },
                "example": {
                  "jsonrpc": "2.0",
                  "error": {
                    "code": -32000,
                    "message": "Not Acceptable: Client must accept both application/json and text/event-stream"
                  },
                  "id": null
                }
              }
            }
          },
          "415": {
            "description": "`Content-Type` is not `application/json`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcError"
                },
                "example": {
                  "jsonrpc": "2.0",
                  "error": {
                    "code": -32000,
                    "message": "Unsupported Media Type: Content-Type must be application/json"
                  },
                  "id": null
                }
              }
            }
          },
          "500": {
            "description": "The server failed before the transport could answer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcError"
                },
                "example": {
                  "jsonrpc": "2.0",
                  "error": {
                    "code": -32603,
                    "message": "Internal server error"
                  },
                  "id": null
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "description": "A JSON-RPC 2.0 request or notification. A batch is an array of these.",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "id": {
            "type": [
              "integer",
              "string"
            ],
            "description": "Omit for a notification; the server then answers 202 with no body."
          },
          "method": {
            "type": "string",
            "description": "`initialize`, `tools/list`, `tools/call`, `ping`, or a notification such as `notifications/initialized`."
          },
          "params": {
            "type": "object",
            "additionalProperties": true,
            "description": "For `tools/call`: `{ name, arguments }`."
          }
        }
      },
      "JsonRpcError": {
        "type": "object",
        "required": [
          "jsonrpc",
          "error",
          "id"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "id": {
            "type": "null"
          }
        }
      }
    },
    "securitySchemes": {
      "mcpOAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "OAuth access token",
        "description": "An OAuth access token for `https://api.musicnerd.net/mcp`, scope `mcp:tools`. An MCP client gets one by adding the server URL: a Music Nerd page opens, the user signs in with Privy and approves the agent. Tokens last five minutes and refresh on their own; disconnecting the agent stops them at once. See [MCP resource metadata](/api-reference/oauth/resource-metadata)."
      }
    }
  }
}
```
