MCP Troubleshooting Guide

Common issues and solutions for Publora MCP Server.

Connection Issues

"API key required" Error

Cause: Missing or malformed Authorization header.

Solutions:

1. Check header format:

   {
     "headers": {
       "Authorization": "Bearer sk_YOUR_API_KEY"
     }
   }

2. Ensure "Bearer" prefix is included:

   Correct: "Bearer sk_abc123..."
   Wrong: "sk_abc123..."

3. Verify no extra spaces:

   Correct: "Bearer sk_abc123"
   Wrong: "Bearer  sk_abc123" (double space)
   Wrong: " Bearer sk_abc123" (leading space)

4. Generate a new key:

   • Go to publora.com → API in the sidebar
   • Click "Generate New Key"
   • Update your configuration

Tools Not Showing in AI Client

Cause: MCP server not loaded properly.

Solution 1: Restart your AI client

MCP servers load on startup. Close and reopen your client completely.

Solution 2: Check config file location

Solution 3: Validate JSON syntax

Use jsonlint.com to check for errors.

Common JSON mistakes:

// Wrong - trailing comma
{
  "mcpServers": {
    "publora": {
      "type": "http",
    }
  }
}
 
// Wrong - missing quotes
{
  mcpServers: {
    publora: {}
  }
}
 
// Wrong - single quotes
{
  'mcpServers': {
    'publora': {}
  }
}

Solution 4: Verify config structure

Correct structure:

{
  "mcpServers": {
    "publora": {
      "type": "http",
      "url": "https://mcp.publora.com",
      "headers": {
        "Authorization": "Bearer sk_YOUR_API_KEY"
      }
    }
  }
}

Solution 5: Check with Claude Code

Run /mcp to see connected servers and their status.

"Connection refused" or Network Error

Cause: Cannot reach mcp.publora.com.

Solution 1: Check internet connection

ping google.com

Solution 2: Verify server is running

curl https://mcp.publora.com/health

Expected response:

{"status":"ok","service":"publora-mcp"}

Solution 3: Check for firewall/proxy

• Ensure HTTPS (port 443) is allowed
• Check corporate proxy settings
• Try from a different network

Solution 4: Check DNS resolution

nslookup mcp.publora.com

Authentication Issues

"API key required" / "Malformed API key" (401)

The MCP server returns one of these two 401 responses if the request is missing a usable API key:

Both responses include:

• A docs field in the JSON body pointing back to this documentation site.
• A WWW-Authenticate: Bearer realm="publora", error="invalid_token", error_description="..." header (RFC 6750). Inspect it with curl -v for the actionable message:

curl -v -X POST https://mcp.publora.com \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Solutions:

1. Check for typos — Keys start with sk_ and are 20-200 characters long.

2. Ensure no quotes around the key in the header value:

   // Correct
   "Authorization": "Bearer sk_abc123..."
    
   // Wrong - extra quotes
   "Authorization": "Bearer \"sk_abc123...\""

3. Use the fallback header if your client / proxy strips Authorization — the server also accepts x-publora-key: sk_<your_key>. Some Cloudflare / reverse-proxy configurations strip the Authorization header, so this is a useful alternative.

4. Generate a new key:

   • publora.com → API in the sidebar
   • Click Generate API Key
   • Update all configurations

5. Verify correct account — Make sure you're logged into the right Publora account.

"Unauthorized" When Calling Tools

Cause: API key doesn't have access to the requested resource.

Solutions:

1. Verify workspace — Check you're connected to the correct Publora workspace

2. Check subscription — Ensure your plan includes API access

3. Verify resource ownership — You can only access your own workspace's data

"oauth_not_supported" (404) on /register or .well-known/oauth-*

Cause: Your MCP client tried to perform OAuth Dynamic Client Registration. Publora MCP uses static API keys, not OAuth, so these paths return:

{
  "error": "oauth_not_supported",
  "error_description": "Publora MCP uses static API keys, not OAuth. Send 'Authorization: Bearer sk_<your_key>' or 'x-publora-key: sk_<your_key>'.",
  "docs": "https://docs.publora.com/mcp/openclaw"
}

Solution: Disable OAuth in your client's MCP configuration and supply a static API key header instead. If the client offers no static-key option, see Client Setup for known-working clients.

Tool Errors

"Platform not found"

Cause: Using an invalid platform ID.

Solution:

1. First call list_connections to get valid platform IDs
2. Platform IDs look like: twitter-123456, linkedin-abc123
3. Don't use generic names like "twitter" — use the full ID

You: "List my connections"
Claude: You have these platforms:
  - linkedin-abc123
  - twitter-xyz789
 
You: "Schedule to linkedin-abc123"  // Correct
You: "Schedule to linkedin"          // Wrong

"Invalid scheduled time"

Cause: Datetime format is wrong.

Solution:

Use ISO 8601 format: 2026-03-01T14:00:00Z

Correct formats:

2026-03-01T14:00:00Z           (UTC)
2026-03-01T09:00:00-05:00      (with timezone offset)
2026-03-01T14:00:00.000Z       (with milliseconds)

Wrong formats:

March 1, 2026
03/01/2026 2pm
2026-03-01 14:00
tomorrow at 9am (AI converts this, but tool needs ISO 8601)

"Post content too long"

Cause: Content exceeds platform character limits.

Platform limits:

Solution: Shorten your content or use a platform with higher limits.

"Post group not found"

Cause: Invalid post group ID or post was deleted.

Solutions:

1. Verify the ID — Post IDs are MongoDB ObjectIds (e.g., 67a1b2c3d4e5f6a7b8c9d0e1)
2. List posts — Use list_posts to see valid post IDs
3. Check filters — The post might have a different status than expected

Session Issues

"Invalid or missing session. Send a POST without mcp-session-id to start."

Cause: MCP session expired or not initialized.

Solution:

This usually resolves automatically. The server creates a new session on the next request.

If persistent:

1. Restart your AI client
2. Check your API key is still valid
3. Verify server is responding:

   curl https://mcp.publora.com/health

Configuration Mistakes

Common Configuration Errors

Wrong - missing "type":

{
  "mcpServers": {
    "publora": {
      "url": "https://mcp.publora.com"
    }
  }
}

Wrong - "url" type instead of "http":

{
  "mcpServers": {
    "publora": {
      "type": "url",
      "url": "https://mcp.publora.com"
    }
  }
}

Wrong - missing Bearer prefix:

{
  "headers": {
    "Authorization": "sk_abc123..."
  }
}

Wrong - trailing slash in URL:

{
  "url": "https://mcp.publora.com/"
}

Correct configuration:

{
  "mcpServers": {
    "publora": {
      "type": "http",
      "url": "https://mcp.publora.com",
      "headers": {
        "Authorization": "Bearer sk_abc123..."
      }
    }
  }
}

Plan Limit Errors

"Post limit reached" / "Scheduled post limit reached"

Cause: You have exceeded a plan-based limit (monthly posts, connections, scheduled posts, or schedule horizon).

Note: The MCP server wraps Publora API limit errors and returns them in the .error field of the response (e.g., "Post limit reached", "Scheduled post limit reached"). The underlying API uses HTTP 403 Forbidden, but MCP clients will see the descriptive error string, not the HTTP status code.

Solutions:

1. Check your plan limits:
   • Starter (free): 15 posts/month (account-wide) (dashboard only — apiAccess: false, mcpAccess: false). Starter users cannot use the API or MCP at all; attempting to do so returns an access error. The Starter plan also excludes Twitter/X — users must upgrade to Pro or Premium to post to Twitter. Upgrade to Pro or Premium for API/MCP access.
   • Pro: 100 posts/month per connection
   • Premium: 500 posts/month per connection
2. Upgrade your plan — Higher tiers have higher limits
3. Wait for the monthly reset — Monthly post counts reset at the start of each billing cycle

mcporter / OpenClaw Issues

"Unknown MCP server" or "auth required" Error

Cause: mcporter expects the Claude Desktop / Cursor-compatible top-level config key mcpServers (not servers). With the wrong key, the file fails schema validation and mcporter falls back to treating the server as needing OAuth — which Publora MCP does not support.

Solution 1: Use the correct config file shape

Create config/mcporter.json:

{
  "mcpServers": {
    "publora": {
      "url": "https://mcp.publora.com",
      "headers": {
        "Authorization": "Bearer sk_YOUR_API_KEY"
      }
    }
  }
}

Then run:

mcporter list --config config/mcporter.json

If mcporter list still reports auth required even with the Bearer header in this config, mcporter is merging another config source (e.g. ~/.claude.json, ~/.mcporter/). Run with --verbose to see which file is supplying the entry:

mcporter list --config config/mcporter.json --verbose

Do not run mcporter auth publora. Publora MCP uses static API keys, not OAuth. The auth command performs OAuth Dynamic Client Registration against /register, which the server does not implement — it will fail with a 404.

Solution 2: Check mcporter version

Update to the latest version:

npm install -g mcporter

Solution 3: Test connection manually

curl -X POST https://mcp.publora.com \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

Note: The Accept header is technically required by the MCP Streamable HTTP spec, but our server auto-fixes missing headers for compatibility with clients that don't send them.

Debugging Tips

Enable Verbose Logging

Claude Code:

CLAUDE_DEBUG=1 claude

Python client:

import logging
logging.basicConfig(level=logging.DEBUG)

Test with cURL

Health check:

curl -v https://mcp.publora.com/health

Test authentication:

curl -X POST https://mcp.publora.com \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

Check Tool Response

When a tool fails, check the response content:

result = await session.call_tool("list_posts", {})
print(result.content[0].text)  # Check for error messages

Getting Help

If you're still stuck:

1. Documentation: Check docs.publora.com
2. Email: serge@publora.com
3. Twitter/X: @publorainc

When reporting issues, include:

• Your AI client (Claude Code, Cursor, etc.) and version
• Config file (with API key redacted)
• Full error message
• Steps to reproduce
• Output of curl https://mcp.publora.com/health