Unabyss

Personal and company context from Unabyss, available to your agent through the Unabyss MCP server.

The plugin is a declaration, not an implementation. mcp.json names the server; the client connects to it, authorizes it, and surfaces its tools. The skill teaches the agent when and how to use them.

Layout

unabyss-vellum/
├── plugin.json      Agent Plugins manifest
├── mcp.json         Declares the Unabyss MCP server
├── package.json     Vellum plugin manifest
└── skills/
    ├── unabyss-context/
    │   └── SKILL.md                       Loading and saving context
    └── unabyss-setup/
        ├── SKILL.md                       First connection and diagnosis
        └── scripts/
            └── check-connection.ts        Read-only connection doctor

The MCP server

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "unabyss": {
      "type": "streamable-http",
      "url": "https://mcp.unabyss.com"
    }
  }
}

That is the whole integration surface. Once the client connects, the server's tools — whoami, query, agentic_query, store, list_skills, export_* — land in the agent's catalog directly.

Authorization is the client's job

Agent Plugins 1.0.0 defines no portable OAuth or credential-reference fields: authentication is client-managed, and headers in mcp.json is literal package data that must never carry secrets. So there is nothing to configure here and nothing to exchange with Unabyss ahead of time.

Unabyss's server is fully spec-compliant, which is what makes that work. For anyone implementing the client side, the relevant properties are:

• Protected resource metadata (RFC 9728) at the origin root. The server sends a bare 401 with no WWW-Authenticate header and 404s the path-suffix metadata URL — both spec-legal, but a client that only parses the challenge header, or that never falls through to the root, discovers nothing.
• The RFC 8707 resource identifier is https://mcp.unabyss.com, the bare origin, even though the endpoint accepts any path under that host. Derive it from published metadata, not from the endpoint URL.
• PKCE S256 is advertised and required; plain is refused.
• Both Client ID Metadata Documents and dynamic client registration are offered, so no client ID needs to be pre-registered by hand.

The skills

unabyss-context covers loading context (whoami → query, escalating to agentic_query only when the first pass is thin), saving it (store), and the rest of the catalog — playbooks, connected apps, exports.

unabyss-setup covers the one-time per-connection setup and telling an unauthorized connection apart from a broken server. It deliberately describes no steps: the server owns the flow and returns each message with a trailing > Next step (agent): note naming the next call, so the skill teaches the agent to follow that note rather than carrying a copy of a sequence that changes server-side.

They are split because they activate on different situations. Loading context fires on "what do you know about me"; setup fires when a tool answers with onboarding guidance instead of data — which is exactly the moment a context-loading description would not match.

Some clients namespace MCP tools by server, so they may appear as unabyss__query rather than query. Both skills say to use whatever names the catalog actually shows.

The connection doctor

bun run skills/unabyss-setup/scripts/check-connection.ts

Probes the server unauthenticated and reports whether it is reachable and whether its authorization metadata is complete:

Server:      https://mcp.unabyss.com
Reachable:   yes (HTTP 401)
Challenge:   no WWW-Authenticate header (spec-legal; discovery falls back to well-known probing)
Metadata:    https://mcp.unabyss.com/.well-known/oauth-protected-resource
Resource:    https://mcp.unabyss.com
Scopes:      read write
Issuer:      https://mcp.unabyss.com
PKCE:        S256 supported
Registration: Client ID Metadata Documents, dynamic client registration

OK    Unabyss is reachable and its authorization metadata is complete.

It exists to separate "the server is broken" from "you have not authorized it yet" — a distinction a failing tool call cannot make on its own. Everything it does is read-only: it never starts an authorization flow, registers a client, or touches a token. Exit code is 0 on OK and 1 on any FAIL.

Installation

assistant plugins install unabyss

This is the install command, resolving the plugin by name from the Vellum marketplace catalog. It works once the plugin has been published there, which is a reviewed step.

Then authorize the Unabyss MCP server through your client's connection settings.

Installing from this repository

assistant plugins install https://github.com/Unabyss/unabyss-vellum

Installing by URL is for QA: it is how a version gets exercised on a real assistant before it is published for review. It clones this tree verbatim and bypasses the catalog, so the source is untrusted and the CLI prints a warning naming it. Point it at a branch or a fork to test a change that is not on main yet.

Use the name, not the URL, once the plugin is published.

Development

bun install
bun run typecheck
bun test

Tests cover the doctor's pure helpers — well-known URL construction and probe ordering, WWW-Authenticate parsing, manifest reading, and the registration summary. Nothing in the suite touches the network. CI runs the same two commands on every pull request, and additionally validates plugin.json and mcp.json against the published Agent Plugins schemas.

Bun is the runtime: it is what Agent Skills scripts are invoked with, and the test suite uses bun:test. The doctor also runs unmodified under Node from v24 (earlier versions cannot execute a .ts entrypoint), so its entrypoint check does not rely on import.meta.main alone — a runtime lacking it would otherwise exit 0 having printed nothing, which reads as a healthy server.

License

MIT. See LICENSE.

Details