Custom MCP — Bring Your Own Server
Phyllax ships with 37 built-in integrations, but you're not limited to them. Any service that exposes an MCP (Model Context Protocol) server — hosted by the vendor or self-hosted by you — can be connected as a Custom MCP. Its tools become available in the AI chat alongside the built-in integrations.
This is the right path when:
- You want to connect your company's internal tools (CRM, ticketing, deploy systems, analytics) that your engineering team has wrapped in an MCP server.
- A vendor offers a hosted MCP that isn't yet in Phyllax's built-in list (e.g. Cloudflare, GitHub's MCP, niche SaaS).
- You're running an open-source MCP server locally or on a private server and want Phyllax to be the client.
What works today
| Feature | Status |
|---|---|
| Connect any Streamable HTTP MCP server (the modern transport, 2025-03-26 spec) | ✓ |
| SSE transport (legacy MCP spec) — handled by the SDK transport's fallback | ✓ |
| OAuth 2.1 with Dynamic Client Registration (RFC 7591) + PKCE + .well-known discovery | ✓ |
| Static auth header (Bearer / API key / custom) | ✓ |
| No-auth (public/anonymous) servers | ✓ |
| Tools appear in AI chat alongside built-in integration tools | ✓ |
| Per-server AI guidance (optional textarea — tells the AI when and how to use this server) | ✓ |
| Schedule monitoring runs against custom MCPs (cron + notification cards) | Coming soon |
Connecting a custom MCP — step by step
- Open Phyllax → Integrations tab. Scroll to the bottom of the page.
- Find the "Custom" category. Click the + Add custom MCP tile.
- Fill in the modal:
- Display name — a recognizable name, e.g.
Internal CRM. Used to generate a stable ID for the integration. - MCP server URL — the full
https://...endpoint of the MCP server. - AI guidance (optional) — a short note telling the AI when and how to use this server. Phyllax injects this into the system prompt alongside the server's tool list. See AI guidance below.
- Authentication — pick one of three tabs:
- None — for public or anonymous servers.
- Static auth header — paste an
Authorization: Bearer <token>value, or whatever the server expects (e.g.X-API-Key: <key>). - OAuth 2.1 — for hosted MCPs that advertise OAuth via
.well-known/oauth-authorization-server. No client ID or secret needed; Phyllax registers itself dynamically (RFC 7591) and stores the resulting tokens encrypted.
- Display name — a recognizable name, e.g.
- Click Save & Test. Phyllax saves the configuration, then runs an
initialize+tools/listhandshake against the server. For OAuth, it opens your browser to the authorization page; after you approve, the local redirect closes the loop and the handshake completes. If the test succeeds, the tile shows a green dot and the list of available tools. If it fails, the inline error explains what went wrong (401, 404, network unreachable, OAuth timeout, etc.).
You can edit or remove a custom MCP at any time by hovering its tile (gear icon for edit, trash icon for delete).
Hosted MCP servers — current ecosystem
Every major SaaS vendor with an MCP offering uses OAuth 2.1 by default. Custom MCP supports OAuth 2.1 with Dynamic Client Registration, so any of the major hosted MCPs work today with a click-to-authorize flow.
| Service | URL | Auth method |
|---|---|---|
| Atlassian (Jira, Confluence) | https://mcp.atlassian.com/v1/mcp/authv2 | OAuth (default) or static API token |
| Slack official | https://mcp.slack.com/mcp | OAuth |
| Asana | https://mcp.asana.com/v2/mcp | OAuth |
| Linear | https://mcp.linear.app/mcp | OAuth |
| Notion | hosted | OAuth |
| GitHub MCP | hosted | OAuth |
| Cloudflare's various MCPs | various | OAuth |
| Your internal company MCP | https://your-domain/... | Whatever you set up — usually static header |
| Self-hosted open-source MCPs | https://your-server/... | Static header (or no auth if public) |
For OAuth servers: pick the OAuth tab, click Save & Test, and Phyllax opens your browser to the authorization page. After you approve, the redirect closes the loop automatically and tokens are stored encrypted on your machine.
Auth header examples
Common patterns you'll paste into the Header value field:
| Server expects | Example value |
|---|---|
| Bearer token | Bearer ghp_xxxxxxxxxxxxxxxxxxxx |
| API key | ApiKey YOUR_KEY |
| Custom header (paste in name + value) | name=X-API-Key, value=YOUR_KEY |
| Atlassian API token | name=Authorization, value=Bearer YOUR_ATLASSIAN_API_TOKEN |
The header value is stored encrypted at rest on your machine using your OS's secure key storage (Windows DPAPI / macOS Keychain) — same encryption scheme used for the built-in integration credentials.
AI guidance — tell the LLM when to use this MCP
The MCP protocol gives the AI each tool's name, description, and input schema. That's enough for the LLM to call tools correctly, but it doesn't tell the AI when to use this MCP, what counts as urgent in this domain, or how to phrase queries the server expects.
For Phyllax's 37+ built-in integrations, that guidance lives in instructions.md baked into the app. For custom MCPs, the optional AI guidance textarea is your equivalent — a short note prepended to the AI's system prompt whenever this MCP's tools are in play.
When to fill it in:
- Your MCP's tool descriptions are sparse or technical, and the AI needs context.
- The MCP serves a specific domain ("internal ticketing", "company OKR tracker") and the AI should know what kind of queries to send.
- There's a notion of urgency, freshness, or filtering that the LLM should respect.
When to leave it blank:
- The tool names are self-explanatory (
create_ticket,list_tickets,add_comment). - The MCP is for ad-hoc lookups, not scheduled monitoring.
Examples that work well:
"Use for engineering tickets only — bugs and incident reports. P0/P1 priorities are urgent; ignore P3 unless older than 30 days. Always include
project_key=PHXwhen searching."
"This is our company OKR tracker. Quarterly objectives are immutable; weekly check-ins update. When asked about progress, only count items closed in the current quarter."
"Customer support knowledge base. Always cite the document ID in your answer so the user can verify. Don't speculate beyond what the docs say."
Phyllax caps the field at 2000 characters and trims whitespace. You can edit or clear it at any time — changes take effect on the next chat or scheduled run.
How tools appear in chat
Every tool exposed by your custom MCPs is available to the AI assistant alongside the built-in integration tools. The naming convention is <custom-mcp-id>__<tool-name> — for example, if you named your MCP "Internal CRM" (slug: cm_internal_crm) and it exposes a search_contacts tool, the LLM sees cm_internal_crm__search_contacts in its tool list and routes calls back to your MCP server transparently.
You can verify what tools a custom MCP exposes by clicking its tile after a successful Save & Test — the modal shows the discovered tool count and you can drill into each.
Troubleshooting
"Network error: ENOTFOUND"
The URL doesn't resolve. Double-check the hostname. If it's an internal server, make sure your machine is on the VPN.
"Network error: ETIMEDOUT" or "Network error: ECONNREFUSED"
The hostname resolves but no MCP server answers on that path. Verify the URL is the full MCP endpoint (e.g. https://example.com/mcp, not just https://example.com).
HTTP 401 Unauthorized
Auth header is wrong or expired. Re-check the value — common mistakes: missing Bearer prefix, expired token, wrong header name.
HTTP 404 Not Found
Either the URL path is wrong, OR the server's session expired between Save and Test. Click Save & Test again to reconnect.
HTTP 405 Method Not Allowed
Rare — Phyllax's transport falls back to SSE automatically for older MCP servers, so most legacy servers Just Work. If you still see a 405, the server probably needs an extra header or path that isn't part of the MCP spec — check with the server vendor.
OAuth: "Authorization timed out" after 5 minutes
You started the OAuth flow but didn't complete the consent screen within 5 minutes. Click Save & Test again to restart the flow.
OAuth: browser opened but the redirect page never closes
The MCP server's authorization server didn't redirect back to Phyllax's local listener. Two common causes: (1) you closed the auth tab before it redirected, (2) the server refused our dynamically-registered client (rare — most servers that advertise OAuth metadata accept dynamic clients per RFC 7591). Try again, or fall back to a static auth header if the server supports one.
"Could not parse JSON response"
The server returned non-JSON content. Likely a proxy or auth wall in front of the MCP. Verify the URL points directly at the MCP, not a UI.
Test succeeds but the AI doesn't use the tools
Most likely: the AI doesn't know when to use them. Tool names and descriptions alone don't always carry enough context. Add an AI guidance note (described above) — a short statement like "Use for engineering tickets only" gives the model the framing it needs.
Removing a custom MCP
Hover the tile → click the trash icon → confirm. Removes the configuration, the encrypted credential bundle (including any OAuth tokens), and any cached session immediately. Any schedules referencing this MCP will start failing on next run; delete them separately from the Schedules section if you had any.
What's next
The connection layer, chat-side routing, and per-server AI guidance are all live. Still on the roadmap:
- Scheduler integration: define monitor schedules against custom MCPs and get notification cards on the dashboard.
- Per-server icons: upload your own logo for the integration tile.
- Tool catalog browsing: click into a connected MCP and see each tool's schema in the UI.