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. The authentication challenge depends on the deployment and failure:

Inspect the JSON body with:

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 (browser-based clients)

mcp.publora.com supports OAuth 2.1 (Dynamic Client Registration + PKCE) in addition to static API keys. Most clients that can open a browser use it — Claude, Claude Code, Codex/ChatGPT, Cursor, VS Code, Manus and others. Using Claude as the example:

1. Open the directory listing at claude.ai/directory/publora — or add Publora by URL: Customize → Connectors → + → Add custom connector, URL https://mcp.publora.com/mcp.
2. Click Connect → a Publora window opens (sign in if asked), then the consent page: "An application is requesting access to your Publora account", showing which account you are authorizing as.
3. Click Approve. Publora mints a dedicated API key for that client (named MCP (<client> #<id>)) and returns it as the access token — there is nothing to paste. Manage or revoke it any time on the API page in your dashboard.

If you instead see {"error":"oauth_not_supported"} (404) on /register or /.well-known/oauth-*: you are hitting a deployment running in static-key-only mode (OAuth disabled). The public mcp.publora.com has OAuth enabled; a self-hosted/older instance without the OAuth signing secret does not. On such an instance, disable OAuth in your client and send a static key header (Authorization: Bearer sk_... or x-publora-key: sk_...).

Headless CLIs (mcporter, custom agents): the consent step is an interactive web page, so non-interactive clients can't complete it — use a static API-key header instead of the OAuth flow.

Claude asks before using some Publora tools

Cause: In Claude, each connector tool has its own permission: Always allow, Needs approval or Blocked. By default, read-only tools (list_connections, list_posts, get_post, account_context, post_stats, profile_stats, linkedin_list_mentionables) run without asking, and tools that create, change or delete posts, media or LinkedIn activity ask first.

Solution: Open Customize → Connectors → Publora → Tool permissions and set the tool you want to stop confirming to Always allow.

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

ChatGPT: image not attached, or media stuck in uploading

Cause: ChatGPT can't do the presigned upload itself. If it calls get_upload_url, nothing sends the HTTP PUT afterwards, so the media slot stays in uploading and scheduling is refused with 503 MEDIA_UPLOAD_PENDING. If complete_media was called for that slot, the missing upload is marked failed once five minutes have passed since that call, and scheduling then returns 400 MEDIA_UPLOAD_MISSING. An image generated in ChatGPT also has no public URL that could be passed as mediaUrls.

Solution:

1. Use attach_media. Ask ChatGPT to attach the file to the draft with attach_media. ChatGPT passes its own file reference, Publora downloads the file right away, and the post stays a draft.
2. Check the result. In get_post, media[] should list the file with status: "ready". Remove a leftover uploading slot with delete_media, using its mediaId from media[].
3. Schedule with update_post (status: "scheduled" and a future scheduledTime) when you're ready to publish.

attach_media is not in ChatGPT's tool list: the connector is still using the tool list it loaded before the tool existed. Refresh the Publora connector's tools in ChatGPT, or remove the connector and add it again.

ChatGPT can't hand over a generated image as a file (for example, it sends a /mnt/data/… path, which is rejected): use a public image URL with mediaUrls, or attach the image to the draft in the Publora web app.

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..."
  }
}

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: MCP surfaces the full API error in the tool exception. Match stable codes such as POST_LIMIT_REACHED or SCHEDULED_POST_LIMIT_REACHED; the corresponding API error values are "Post limit reached" and "Scheduled post limit reached".

Solutions:

1. Check your limits with account_context — it returns your plan, the platform posts left this month (quotas.monthlyPosts, which starts over at resetAt), how many platform posts can wait in the queue (quotas.scheduledPosts), the latest date you can schedule (quotas.scheduleHorizon.maxScheduledDate) and the platforms your plan allows. See account_context.
2. Know the free plan's limits: Starter allows 15 platform posts a month (account-wide), 3 scheduled platform posts at a time, scheduling up to 7 days ahead and up to 3 connected accounts. It includes API and MCP access (apiAccess: true, mcpAccess: true). New Starter accounts can't publish to X, and Pinterest is connect-only on every plan. Current paid plans set the monthly limit per connection; see publora.com/pricing.
3. Upgrade your plan — Higher tiers have higher limits
4. Wait for the reset — The monthly count starts over at resetAt; queued posts free up scheduled slots as they publish

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 OAuth. Publora MCP supports OAuth, but its consent page is interactive, so a headless mcporter process cannot complete that flow.

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

Don't run mcporter auth publora. mcp.publora.com supports OAuth 2.1 (PKCE, dynamic client registration), but the flow ends on an interactive consent page in a browser, which a headless CLI cannot complete — so authenticate mcporter with a static key header (Authorization: Bearer sk_... or x-publora-key) instead.

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