Codex coordinates the task; LingoBridge processes the document
The local bridge reads JSON-RPC messages from Codex, adds your Bearer API key, and forwards them to the production MCP endpoint. Translation remains asynchronous: create a task, save task_id, then poll until SUCCESS or FAILED.
Create one key for Codex and keep it out of prompts, screenshots, project files, and shared configuration.
Run the verified installer or register the stdio bridge manually with Node.js 18 or later.
Check the MCP registration, shared credits account, and current pricing before creating a paid task.
Submit a representative local document, keep its task_id, and poll until SUCCESS or FAILED.
Prepare Codex, Node.js, and a dedicated API key
Use a separate key for this client so it can be revoked without affecting another integration.
- Install Codex and confirm that the codex command is available in your terminal.
- Install Node.js 18 or later. The local bridge uses the built-in fetch API and does not add a project dependency.
- Create a dedicated API key in the Developer Center. The full key is displayed only once.
- Choose a representative PDF, DOCX, PPTX, or XLSX file no larger than 20 MB. Use the REST API upload workflow for larger files.
Run the verified installer for your operating system
The installer downloads the bridge from the fixed LingoBridge domain, validates the API key against the MCP endpoint, replaces the existing Codex entry named fanyipaiban, and asks you to restart Codex.
$installerUrl = "https://www.fanyipaiban.com/poly/fanyipaiban-mcp-install.ps1"
$installer = Invoke-RestMethod $installerUrl
if ($installer -notmatch "(?m)^# FANYIPAIBAN_MCP_INSTALLER$") {
throw "Installer file is unavailable. Use the manual setup below."
}
& ([ScriptBlock]::Create($installer))installer=$(mktemp)
curl -fsSL https://www.fanyipaiban.com/poly/fanyipaiban-mcp-install.sh -o "$installer"
grep -q "^# FANYIPAIBAN_MCP_INSTALLER$" "$installer" || {
echo "Installer unavailable. Use manual setup below."
rm -f "$installer"
exit 1
}
bash "$installer"; rm -f "$installer"Manual Codex configuration
The installer ultimately registers this local stdio command. Replace the paths with absolute paths on your own computer after downloading the bridge and creating mcp.json.
# Download the bridge to ~/.fanyipaiban/fanyipaiban-mcp-proxy.mjs
# Create ~/.fanyipaiban/mcp.json with: {"apiKey":"YOUR_API_KEY"}
[mcp_servers.fanyipaiban]
command = "node"
args = [
"FULL_PATH/.fanyipaiban/fanyipaiban-mcp-proxy.mjs",
"--config",
"FULL_PATH/.fanyipaiban/mcp.json"
]Verify account and pricing before creating a paid task
Restart Codex and open a new task. First make two read-only calls so you can confirm the server, API key, and current billing rules without creating a translation task.
codex mcp listUse only the LingoBridge MCP tools for this check.
1. Call translation_get_account and summarize the account fields without exposing secrets.
2. Call translation_get_pricing and report the current credits per billable page and the billing unit for PDF, DOCX, PPTX, and XLSX.
3. Do not create a translation task and do not modify any local file.Give Codex a precise, auditable task prompt
Tell Codex which file to use, which target language to request, when to stop polling, and where the result should be saved. The original file should remain unchanged.
Translate ./manual.pdf to Chinese with the LingoBridge MCP tools.
Requirements:
1. Check that the file exists and is no larger than 20 MB. Stop and recommend the REST API if it is larger.
2. Call translation_create_document_task with source_lang=auto, target_lang=cn, and a stable request_id for this operation.
3. Save the returned task_id. Poll translation_get_task every 3 to 5 seconds until status is SUCCESS or FAILED.
4. On SUCCESS, save the result as ./outputs/manual-zh.pdf when this environment permits downloading; otherwise return the short-lived download URL.
5. Report estimated and charged credits. Do not overwrite the source file.
6. Remind me to review scans, tables, diagrams, and business-critical values before delivery.Four MCP tools are currently available online
This list was verified against the production tools/list response. PDF utilities and image translation exist in newer local code but are intentionally omitted until they are deployed to the production MCP server.
translation_get_accountRead available, frozen, used, and recharged credits from the shared account.translation_get_pricingRead the current credits-per-page price and the billable unit for PDF, DOCX, PPTX, and XLSX.translation_create_document_taskCreate an asynchronous translation task. Required inputs are file_name, file_base64, and target_lang; source_lang, parse_engine, and request_id are optional.translation_get_taskRead task status, progress, credits, and short-lived result links by task_id. Continue until SUCCESS or FAILED.Use MCP for an AI workspace and REST API for system integration
MCP and REST API reach the same document translation capability, but they fit different operational contexts.
| Situation | Best option | Reason |
|---|---|---|
| Translate one or several local files while working in Codex | MCP | Codex can read the selected workspace file, create the task, and keep polling in the same task. |
| Backend service, RPA, queue, or batch workflow | REST API | Your system controls multipart upload, Idempotency-Key, retries, logging, and result archiving. |
| A local file is larger than 20 MB | REST API | The production MCP document payload is limited to 20 MB. |
| Test output before writing any integration | Web workspace | Upload a representative sample and review translation and layout before automating the workflow. |
Treat the local key file and result links as secrets
The bridge keeps the key out of prompts and project code, but the credential still needs normal secret-handling discipline.
- The installer stores the API key in plain JSON under the current user profile. Restrict access to that account and do not include the folder in cloud sync or backups shared with others.
- Use a dedicated key per client. Revoke it immediately in the Developer Center if the file, screenshot, terminal log, or device is exposed.
- Codex may ask for permission to read a local file, access the network, or write a downloaded result depending on your workspace and sandbox settings.
- Result download URLs are short-lived. Save approved deliverables promptly and keep the original document for comparison and review.
- Translation and layout retention are not guaranteed to be perfect. Review scans, formulas, tables, diagrams, and business-critical values before delivery.
Diagnose the connection layer by layer
Check registration, session freshness, credentials, file boundaries, and account state in that order.
| Symptom | Likely cause | Action |
|---|---|---|
| fanyipaiban is missing from codex mcp list | The installer did not finish or codex was unavailable in PATH. | Fix the terminal installation, rerun the installer, and confirm the entry before restarting Codex. |
| The MCP entry exists but Codex shows no translation tools | The current Codex task started before the MCP configuration changed. | Restart Codex and open a new task. |
| Invalid API key or HTTP 401 | The key is mistyped, revoked, or no longer active. | Create a new dedicated key and rerun the installer. |
| The file is rejected before task creation | The format is unsupported, the payload is invalid, or the file exceeds 20 MB. | Use PDF, DOCX, PPTX, or XLSX and switch large files to the REST API. |
| The task remains QUEUED or RUNNING | Document processing is asynchronous. | Keep the same task_id and poll at a measured interval; do not create duplicate tasks. |
| INSUFFICIENT_CREDITS | The shared credits balance cannot cover the estimated task. | Recharge the same account, then create a new request. |
Questions before using MCP in daily work
Which tools are currently available on the production MCP server?
The production server currently exposes translation_get_account, translation_get_pricing, translation_create_document_task, and translation_get_task. This page does not advertise tools that are present only in newer local code.
Where does the installer store my API key?
The installer hides the key during input, then stores it as plain JSON in the current user profile at ~/.fanyipaiban/mcp.json. Keep that folder private, use a dedicated key, and revoke the key if the device or file is exposed.
Can MCP translate a local file larger than 20 MB?
No. The current production MCP document payload is limited to 20 MB. Use the public REST API multipart upload workflow for larger files.
Does MCP use a separate credits balance?
No. MCP, REST API, and the web workspace use the same account balance. Document translation is currently charged at 1,500 credits per billable page.
Does Codex need access to my local document?
Yes. Codex must be able to read the selected workspace file before it can send the bytes to the MCP tool. Depending on the workspace and sandbox settings, it may ask for permission to read the file, use the network, or save the result.
Should I trust the translated result without reviewing it?
No. Review scans, formulas, tables, diagrams, numbers, terminology, and layout before delivery. Source quality and document complexity affect the final result.
Verify the connection before translating a paid document
Create a dedicated key, install the bridge, restart Codex, and run the read-only account and pricing check. Then test one representative file and review the result.