Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TonePerfect MCP server Assess my French pronunciation in ./bonjour.wav against 'Bonjour'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Use the TonePerfect pronunciation assessment API from an MCP client. Supports recordings of a known reference text in ten languages. All language packs are experimental; scored dimensions vary by language. Japanese pitch accent is not scored. Phoneme evidence is not a validated correction.
Requires Node.js 18 or later. From this directory:
npm ci
npm testConfigure your MCP client with the absolute path to the built entry point:
{
"mcpServers": {
"toneperfect": {
"command": "node",
"args": ["/absolute/path/to/toneperfect-mcp/dist/index.js"],
"env": { "TONEPERFECT_API_KEY": "YOUR_API_KEY" }
}
}
}Get a key from the dashboard. Keep it in your client's secret configuration, never a public repository. For an npm installation, use npx -y toneperfect-mcp@0.1.0 as the command (or configure command: npx with args: ["-y", "toneperfect-mcp@0.1.0"]). The package publisher is niktoneperfect.
Related MCP server: tts-mcp
list_languages: fetch current supported languages, dimensions and limitations. No key or credits required.
assess_pronunciation: upload a local audio file, base64 audio, or audio downloaded from a URL, with reference text and locale. Sends that audio and reference text to TonePerfect. Only supply recordings you have permission to upload. Uses API credits.
explain_result: explain a previously returned JSON result locally. No API call or credits.
Recordings must be at most 10 MB and 30 seconds. One credit is charged per started 15 seconds of assessable audio; unassessable results are not charged. New accounts currently receive 50 free credits. See pricing for current terms.
The default assessment idempotency key is derived from the audio and fields: identical calls replay within the API's retention window. Set a new explicit key for an intentionally new assessment of identical input. Scores are display grades, not accuracy percentages or exam levels. Check assessable and the language-specific capabilities before displaying feedback.
npm run pack:mcpbThis builds and validates toneperfect.mcpb for compatible desktop clients. It contains the server and dependencies, not your key. This is a local stdio server, not a hosted HTTP connector.
server.json targets app.toneperfect/pronunciation. Publishing requires both an available npm package and verification of the domain namespace. The file alone does not create a registry listing. The MCP registry listing requires a separate publication step; installing the npm package does not create that listing.
MIT licensed. API reference. Contact: nik@toneperfect.app.
Score a recording of someone reading a known reference text (POST /v1/assess). Give the audio as a local file path, base64, or an http(s) URL (WAV, MP3, M4A, Ogg or WebM; 0.15-30 s; max 10 MB), plus the reference text and locale. Returns a short summary and the full JSON (sentence, word and sound scores, expected vs heard, timings, billing). Uses the API key in TONEPERFECT_API_KEY; 1 credit per started 15 s of assessable audio.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | general (default), connected_speech (enables Mandarin component correction decisions) or isolated_word. | general |
| text | No | The expected words the speaker read. Required unless pinyin is given (Mandarin only). Numbers written as words. | |
| pinyin | No | Mandarin only: numbered-tone pinyin, one syllable per character, e.g. "ni3 hao3". | |
| filename | No | Optional filename sent with the upload (helps format detection). | |
| language | No | Locale: zh-CN, en-US, fr-FR, es-419, de-DE, it-IT, pt-BR, ru-RU, ko-KR (beta), ja-JP (beta). | zh-CN |
| audio_url | No | http(s) URL to download the audio from. | |
| audio_path | No | Path to a local audio file (~ is expanded). | |
| audio_base64 | No | Audio bytes as base64 (a data: URL prefix is accepted). | |
| idempotency_key | No | Optional. Defaults to a hash of the audio and fields, so repeating the identical call within 24 h returns the stored result without charging again. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses important operational context: API key via TONEPERFECT_API_KEY, 1 credit per started 15 s of assessable audio, accepted audio sources and formats, duration and size limits, and the shape of the return value. It does not cover rate limits or failure behavior, but it is substantially more informative than the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded: the action and endpoint come first, followed by input requirements, constraints, return shape, auth, and cost. Every sentence adds practical information, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given nine parameters, no output schema, and annotations that only cover safety and idempotency, the description is complete enough for an agent to call the tool correctly. It explains audio input modes, format/size/duration limits, reference text and locale requirements, return contents, auth, and billing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds material constraints not present in the schema: accepted audio sources, supported formats, 0.15-30 s duration, and 10 MB maximum. It also ties the reference text and locale to the task, though it does not elaborate on task/pinyin/idempotency semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: score a recording of someone reading a known reference text, and names the endpoint POST /v1/assess. It is clearly distinct in substance from list_languages and explain_result, but it never explicitly differentiates itself from those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the core use case clear: assessing a recording against a known reference text, with input constraints and supported formats. However, it gives no explicit when-to-use vs alternatives guidance, does not mention list_languages or explain_result, and leaves the agent to infer when this tool is preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain a TonePerfect assessment JSON (the output of assess_pronunciation) word by word: what each score means, which sounds were flagged and what to practise. Runs locally; no API call, no credits.
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes | The assessment JSON object, or it as a string. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds useful operational context that annotations cannot express: it runs locally, makes no API call, and consumes no credits. It does not describe failure behavior on malformed input, which is the main remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with the resource, that still packs scope, output granularity, and the no-cost constraint. No filler and nothing repeated from the name or title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only analysis tool with no output schema, the description gives enough: input provenance, what the explanation covers, and that there is no side effect or cost. Only the shape of the explanation output and behavior on invalid JSON are left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and there is only one parameter, so the schema already documents that it accepts the assessment object or its string form. The description adds the provenance of that value (output of assess_pronunciation), but nothing about format tolerance or validation beyond that. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (explain) plus a precisely scoped resource (a TonePerfect assessment JSON) and granularity (word by word, score meanings, flagged sounds, practice advice). It also names the sibling that produces the input, so an agent can distinguish this from assess_pronunciation without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly places itself downstream of assess_pronunciation ('the output of assess_pronunciation'), which tells an agent when to reach for it. It offers no explicit exclusions or alternative routes, but the sibling set is small and the ordering between the two tools is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the languages, scored dimensions and limits of the TonePerfect pronunciation assessment API (GET /v1/capabilities). Free, no API key needed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a safe, read-only, idempotent operation. The description adds meaningful behavioral context beyond them by disclosing the exact GET endpoint and that access is free with no API key required, though it does not describe the response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single tightly written sentence that front-loads the primary purpose and packs in the endpoint, cost, and authentication details without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and annotations that already cover its safety profile, the description provides everything needed to call it correctly: what it returns, the endpoint, and the access requirements. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so there are no parameter semantics to explain and the baseline score of 4 applies. The description does not need to compensate for any schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ("List") and names the exact resources returned: languages, scored dimensions, and limits. It also identifies the API endpoint, making the tool's purpose unambiguous and clearly distinct from the sibling assessment and explanation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It conveys useful context that the tool is free and requires no API key, but it does not explicitly state when to use this tool versus the sibling tools or what prerequisites or follow-up actions are appropriate. Usage is implied rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0assess_pronunciationexplain_resultlist_languagesScored across 3 tools
Each tool maps to a clearly distinct stage of the workflow: discovery (list_languages), assessment (assess_pronunciation), and post-hoc interpretation (explain_result). There is no overlap in inputs or outputs, and explain_result explicitly references the output of assess_pronunciation, reinforcing the pipeline.
All three names follow a strict snake_case verb_noun pattern (list_languages, assess_pronunciation, explain_result). The verbs are accurate and consistent in style, with no mixed conventions.
Three tools is a tight, well-justified surface for a focused API wrapper covering capabilities, scoring, and result explanation. Every tool earns its place and none appears redundant or thin.
The core lifecycle (discover capabilities, assess audio, explain scores) is fully covered with no dead ends for the primary use case. Minor gaps remain, such as checking credit balance or listing/batch-assessing multiple recordings, but these are workarounds rather than blockers.
Pronunciation assessment, phoneme scoring, speaker voice ID, audio transcription, speech synthesis.
Pronunciation scoring, speech-to-text, and text-to-speech for language learning
MCP server for Speech-to-Text
FalaAI API MCP server: transcribe audio, diagnose conversations, audit compliance (ISO 18295-1).
