Best practices for setting up custom MCP servers with Onyx Agents?

[BittuChan]

Hey everyone,
I've been running a self-hosted Onyx instance (Docker deployment) for a few weeks now and really loving the agent workflow. The built-in actions are solid, but I'm looking to extend my agents with some custom MCP servers for internal tooling at our small team.

I got the basic MCP setup working by following the Actions docs, but I'm running into a couple of issues:

• Authentication flow - when using OAuth-based MCP servers, is there a recommended pattern for handling token refresh? I have an agent that connects to our internal API and the tokens expire after 24h. Right now I'm manually re-authenticating which isn't great.

• Error handling - when an MCP tool fails (network timeout, auth issue, etc), the agent sometimes gets confused and keeps retrying the same broken call.

Any tips for making agents handle failures more gracefully?

I've checked the MCP docs and looked through some GitHub issues but couldn't find much on real-world setup patterns. Would love to hear how others are structuring this, especially for small teams running self-hosted.
Thanks!

[Shiven0504]

hello @BittuChan, I've tried custom MCP servers with Onyx recently so here are my suggestions:

1. Token Refresh

• For OAuth flows with expiring tokens, the cleanest approach I've found is implementing a lightweight proxy service that sits between Onyx and your API. The proxy handles token refresh automatically and Onyx just authenticates once to the proxy with a long-lived credential. We built ours in Node.js (about 100 lines) and it's been rock solid.
• Alternatively, if your MCP server implementation supports it, you can handle refresh logic in the server itself before forwarding requests. This keeps everything in one place but requires your MCP server to be stateful.

2. Shared vs Per-User Auth
   For a 5-person team, shared auth is totally fine and way simpler. We use a dedicated service account for most internal tools. The key is:

• Make sure your API has basic audit logging so you can trace which Onyx user triggered which action
• Use read-only credentials where possible
• Reserve per-user auth for tools that genuinely need user-specific permissions (like email sending, calendar access, etc)

[Shiven0504]

If you're running multiple custom MCP servers, keep a simple markdown doc with your server configs and authentication setup. This makes onboarding new team members way easier.

Hope this helps! Let me know if you want me to share our proxy service code, I'll be happy to open source it if useful!

[BittuChan]

hey @Shiven0504, This is super helpful, thank you! The proxy approach for token refresh makes a lot of sense. I was overthinking it trying to handle everything in the MCP server itself. I'll simply spin up a simple Express proxy shortly.

[BittuChan]

Also really appreciate the point about structured error responses. I realized our MCP server was just throwing generic 500s which explains why the agent kept getting confused. Switched to proper error types and the retry behavior is already way better.

Marking this as resolved. Thanks again for the detailed writeup!

[jingchang0623-crypto]

Setting up custom MCP servers is becoming a common pattern. Here are some lessons from our deployment:

Our MCP setup approach

We run multiple MCP servers through OpenClaw for our agent operations. The key patterns that worked:

1. Capability scoping per server

Don't try to build a "万能" MCP server. Instead:

• Feishu MCP server → only handles document operations
• Web fetch MCP server → only handles URL content extraction
• Memory MCP server → only handles long-term memory queries

This keeps each server focused and debuggable.

2. Security boundaries

We learned this from the ClawHavoc security incident (820+ malicious skills in the ecosystem). Now every MCP server runs with:

• Explicit tool allowlist — only whitelisted operations
• No shell execution — removed exec from MCP toolset
• Request validation — every tool call validates parameters before execution

3. Connection management

For error handling (related to the other discussion about connection closure), we use:

• Graceful degradation — if MCP server goes down, agent falls back to built-in tools
• Health checks — periodic ping to ensure server responsiveness
• Session isolation — each agent session gets its own MCP connection, preventing cross-agent contamination

Example minimal MCP server structure

// A focused MCP server for Feishu operations
const server = {
  name: "feishu-doc",
  tools: ["read_doc", "write_doc", "append_doc"],
  permissions: {
    exec: false,           // No shell access
    file_write: "feishu",  // Only to Feishu docs
    network: "api.feishu.cn" // Only allowed domain
  }
};

Resources

• MCP protocol explained: https://miaoquai.com/glossary/mcp-explained.html
• Our MCP security analysis (after ClawHavoc): https://miaoquai.com/stories/mcp-security-lessons.html

Would love to hear how others are handling MCP server capability negotiation and discovery.