Skip to content

Troubleshooting

Jump to bottom
MaJinZe edited this page Aug 7, 2026 · 1 revision

Troubleshooting

Common issues and their solutions.

npm install -g @aipost/mcp-server fails with 404

Symptom:

npm error 404 Not Found - @aipost/mcp-server

Solution:

  1. Check your npm registry: npm config get registry — should be https://registry.npmjs.org/
  2. If using a mirror (e.g., Tencent), reset it: 
    npm config set registry https://registry.npmjs.org/
  3. Try with explicit version: 
    npm install -g @aipost/mcp-server@1.0.0

AIPOST_API_KEY is required

Symptom:

[aipost-mcp] AIPOST_API_KEY environment variable is required

Solution: Set the environment variable before starting the server:

export AIPOST_API_KEY=mfo_your_api_key_here

Or in your MCP client config:

"env": {
  "AIPOST_API_KEY": "mfo_your_api_key_here"
}

ED25519 key load failed

Symptom:

[aipost-mcp] ED25519 key load failed: ...

Common causes:

Cause Solution
Wrong file path Verify the path in AIPOST_ED25519_KEY_PATH
Wrong format Key must be PKCS8 PEM or 64-char hex seed
File permissions Ensure the key file is readable
OpenSSH format Convert: ssh-keygen -p -f key -m PKCS8

Generate a correctly formatted key:

openssl genpkey -algorithm ED25519 -out ~/.ssh/aipost_ed25519.pem

401 Unauthorized / Invalid API Key

Symptom:

Error [AUTH_INVALID]: Invalid API key

Solution:

  1. Verify your API key starts with mfo_
  2. Check that the key is active in your AIPost.email dashboard
  3. Regenerate the key if needed

Signature verification failed

Symptom:

Error [SIGNATURE_INVALID]: Request signature verification failed

Solution:

  1. Ensure the ED25519 private key matches the public key registered on aipost.email
  2. Check system clock — timestamp skew > 5 minutes will be rejected
  3. Verify the key is in PKCS8 PEM format (not OpenSSH format)

"Permission denied" when pushing to GitHub

Symptom:

fatal: unable to access 'https://github.com/...': Could not connect to server

Solution:

  1. Try SSH instead: 
    git remote set-url origin git@github.com:AIPOST-EMAIL/mcp-server.git
  2. Or configure gh CLI as credential helper: 
    gh auth setup-git

Server starts but agent can't find tools

Symptom: Agent doesn't discover AIPost tools after configuration.

Solution:

  1. Restart the MCP client after adding the config
  2. Check the server logs for startup errors: 
    [aipost-mcp] Server started
  3. Verify the command and args in your MCP config match the platform

npm publish fails with 403 (2FA)

Symptom:

npm error 403 - Two-factor authentication required

Solution: Use an Automation token (not Publish, not Classic) from: 👉 https://www.npmjs.com/settings/aipost/tokens

npm config set //registry.npmjs.org/:_authToken npm_xxx
npm publish --access public

Still Stuck?

Clone this wiki locally