Docs

Choose an identity mode

Skynest runs in one of two modes, selected by the AUTH_PROVIDER environment variable. Pick one per deployment — there is no in-app sign-in picker.

Prerequisites

• A Vercel account (Hobby works; Pro unlocks longer function timeouts)
• An Azure Blob Storage account — required in both modes for the persistent OAuth client registry
• Either a GitHub account (GitHub mode) or a Microsoft Entra tenant with admin access (Entra mode)
• pnpm ≥ 9 and Node.js ≥ 20 locally, plus the Vercel CLI (pnpm add -g vercel)

Common setup (both modes)

Do these regardless of the mode you chose.

1. Fork, clone, and install

git clone https://github.com/<you>/skynest.git
cd skynest
pnpm install

2. Generate OAuth signing keys

Skynest issues RS256-signed JWTs for MCP OAuth. Generate the key pair and paste each full PEM block (including the -----BEGIN...----- lines) into Vercel as OAUTH_PRIVATE_KEY and OAUTH_PUBLIC_KEY:

pnpm oauth:gen-keypair

3. Create the Vercel project and connect Vercel Blob

1. Import your fork at vercel.com/new (Next.js is auto-detected) — don't deploy yet.
2. Open the project's Storage tab → Create Database → Blob, then Connect. This injects BLOB_READ_WRITE_TOKEN automatically — do not set it by hand.

4. Provision Azure Blob for the OAuth client registry

The dynamic OAuth client registry is stored in Azure Blob so registrations survive across serverless instances. This is required in both modes. Create a storage account and set one credential plus (optionally) the container name:

AZURE_STORAGE_ACCOUNT_URL=https://<account>.blob.core.windows.net
# or: AZURE_STORAGE_CONNECTION_STRING=<connection-string>
AZURE_BLOB_CONTAINER=skynest          # optional, defaults to "skynest"

5. Set the common environment variables

AUTH_SECRET=<random>                  # openssl rand -base64 32
NEXTAUTH_URL=https://<your-app>.vercel.app
OAUTH_PRIVATE_KEY=<from step 2>
OAUTH_PUBLIC_KEY=<from step 2>

# Primary document store (Vercel Blob)
CONTEXTNEST_STORAGE=blob
CONTEXTNEST_STORAGE_PROVIDER=vercel   # or "azure" to store documents in Azure too
CONTEXTNEST_BLOB_PREFIX=vault

The full, categorized list — including optional and webhook variables — is in the Environment variables section.

6. Deploy

Push to your default branch — Vercel auto-deploys:

git push origin main

If you registered your OAuth App / Entra redirect URI before the final URL was known, update it now to the deployed URL and redeploy.

7. Verify

Then connect an AI tool following Connecting your AI tool.

Identity & sign-in

A single AUTH_PROVIDER selects the whole deployment’s identity mode — there is no dual sign-in picker.

Authorization (access control)

Decides whether a signed-in caller gets mcp:write, mcp:read, or a 403. See the Access control section.

OAuth token signing & registration

Trusted issuer (dual authorization server)

Optional. Leave both unset to keep self-issued-token-only behavior. Setting the issuer makes the audience mandatory (fails closed).

Primary document store

Vercel Blob is the default cloud store; Azure Blob and local filesystem are the alternatives.

Azure Blob — document store & OAuth client registry

The OAuth client registry is always Azure-backed, so one of these credentials is required in production in BOTH modes. The same account also serves the primary store when CONTEXTNEST_STORAGE_PROVIDER=azure. Distinct from the VAULT_AZURE_* sync vars below.

Vault sync (audit trail)

Records every write to a durable backend. All vars support a per-vault suffix override (e.g. VAULT_REPO_<VAULTID>).

Vault admin endpoint (init-from-git)

Only needed to use the /api/vault/init-from-git initialization endpoint.

read.ai webhook

Only needed if you use the read.ai meeting-ingest webhook.

Local development & escape hatch

Never set MCP_AUTH_DISABLED in a production deployment. See Local development.

How the level is decided

The check runs against whichever identity mode is active (see Deploying Skynest):

• GitHub mode — the caller's permission level on the repo named by AUTHZ_GITHUB_REPO is checked with their own GitHub token. Push/admin access grants write, pull access grants read, and no access is none.
• Entra mode — group membership decides the level. Members of AUTHZ_ENTRA_WRITE_GROUP_ID get write, members of AUTHZ_ENTRA_READ_GROUP_ID get read, and everyone else is none. Membership is read from the ID token's groups claim, falling back to a Microsoft Graph checkMemberGroups call when the claim is absent (large group memberships get overaged out of the token). Each variable accepts a comma-separated list of group IDs.

Enforced twice

Scope is enforced at issuance and at the point of use. Even if a read-only token somehow reached a write path, all seven write tools (create_document, update_document, delete_document, publish_document, stage_drift_suggestion, approve_suggestion, reject_suggestion) re-check for mcp:write and reject the call before touching storage.

Trusted issuer (dual authorization server)

Skynest normally issues its own OAuth tokens. Optionally, it can also accept tokens issued directly by a trusted Entra tenant — for example an on-behalf-of token from a Copilot Studio connector — without changing the self-issued flow at all. Set MCP_TRUSTED_ISSUER and MCP_TRUSTED_AUDIENCE to enable it.

When set, an incoming token whose iss matches the trusted issuer is verified against that tenant's JWKS with an exact audience match, then run through the same AuthorizationProvider as above (its groups claim feeds the Entra check). Every other token — and all tokens when the vars are unset — takes the normal self-issued path unchanged. The .well-known/oauth-protected-resource document advertises the trusted issuer as a second entry in authorization_servers whenever it is configured.

Claude Code CLI

claude mcp add --transport http skynest https://YOUR_SKYNEST_URL/api/mcp

Restart Claude Code. On first use you'll be prompted to sign in with GitHub.

{
  "mcpServers": {
    "skynest": {
      "type": "http",
      "url": "https://YOUR_SKYNEST_URL/api/mcp"
    }
  }
}

Claude Desktop App

1. Open the Claude Desktop app and go to Settings.
2. Navigate to Integrations and click Add MCP Server.
3. Enter:

   Name:      skynest
   URL:       https://YOUR_SKYNEST_URL/api/mcp

4. Save. You'll be redirected to sign in with GitHub on first use.

Claude Code App (Desktop)

1. Open Claude Code and go to Settings.
2. Navigate to MCP Servers and click Add Server.
3. Enter:

   Name:      skynest
   Transport: HTTP
   URL:       https://YOUR_SKYNEST_URL/api/mcp

4. Save and restart. You'll be prompted to sign in with GitHub on first use.

Cursor

Add to .cursor/mcp.json (or the global Cursor MCP config):

{
  "mcpServers": {
    "skynest": {
      "url": "https://YOUR_SKYNEST_URL/api/mcp",
      "transport": "http"
    }
  }
}

Reload Cursor. On first use, a browser window will open for GitHub OAuth sign-in.

Other MCP-compatible tools

Skynest exposes a standard MCP HTTP endpoint with OAuth 2.1. Any tool that supports MCP over HTTP with OAuth 2.1 should work — use https://YOUR_SKYNEST_URL/api/mcp as the endpoint (or https://YOUR_SKYNEST_URL/api/mcp/YOUR_VAULT_ID for a specific vault).

Create the skill file

Save the following template to ~/.claude/skills/skynest/skill.md (create the directory if it doesn't exist). Customise the description frontmatter and the vault structure section to match your own vault layout and tags.

---
name: skynest
description: Use when starting any session that involves your vault, when needing context on stored knowledge, when asked to remember something, or when completing work that should be persisted.
---

# Skynest — Persistent Knowledge Vault

## Overview

Your Skynest vault is a knowledge base accessible via MCP. It stores documents,
notes, processes, and any structured knowledge you choose to save.
**Query it at session start** when the work touches topics you've previously
documented. **Save significant learnings** before ending a session.

## MCP Connection

The vault is accessed via the **skynest** MCP server. All tools are prefixed
`mcp__skynest__*`.

Before calling any tool, load the schema via ToolSearch:
```
ToolSearch({ query: "select:mcp__skynest__vault_info" })
```

For bulk loading all skynest tools:
```
ToolSearch({ query: "skynest", max_results: 30 })
```

## Session Start Protocol

At the start of any substantive session, run at minimum:

```
mcp__skynest__vault_info          → confirm connection, orient to vault identity
mcp__skynest__search(query)       → find documents relevant to the current task
```

## Selector Syntax (for `resolve` tool)

| Pattern        | Meaning                     | Example               |
|----------------|-----------------------------|-----------------------|
| `#tag`         | Documents with this tag     | `#project`            |
| `#tag1 + #tag2`| AND — must have both        | `#project + #active`  |
| `#tag1 | #tag2`| OR — has either             | `#project | #process` |
| `type:document`| Filter by node type         | `type:document`       |

**Hops** (graph traversal depth): default 2.
Use `hops: 1` for fast single-doc lookups; `hops: 3` for deep context on
interconnected topics.

## Common Operations

```javascript
// Search by topic
mcp__skynest__search({ query: "your topic here", hops: 2 })

// Find by tag
mcp__skynest__resolve({ selector: "#project + #active", hops: 2 })

// Read a specific document
mcp__skynest__read_document({ uri: "nodes/your/path" })

// List all documents
mcp__skynest__list_documents({ type: "document", status: "published" })
```

## Saving Knowledge

Use this when asked to remember something, or when you complete work with
lasting value:

```
1. mcp__skynest__create_document({ path, title, type, tags, body })
2. mcp__skynest__update_document({ path, body })   ← if document already exists
3. mcp__skynest__publish_document({ path, author: "claude@claude.ai", note: "..." })
```

**Document types:** `document`, `snippet`, `glossary`, `persona`, `prompt`,
`source`, `tool`, `reference`, `skill`

**Always publish after creating/updating** — drafts are not visible to AI agents.

## Quick Reference

| Goal              | Tool                              | Key Params                          |
|-------------------|-----------------------------------|-------------------------------------|
| Orient to vault   | `mcp__skynest__vault_info`        | —                                   |
| Search by topic   | `mcp__skynest__search`            | `query`, `hops`                     |
| Filter by tag     | `mcp__skynest__resolve`           | `selector`, `hops`                  |
| Read one doc      | `mcp__skynest__read_document`     | `uri`                               |
| Read a pack       | `mcp__skynest__read_pack`         | `id`, `hops`                        |
| List documents    | `mcp__skynest__list_documents`    | `type`, `tag`, `status`             |
| Create new        | `mcp__skynest__create_document`   | `path`, `title`, `type`, `tags`, `body` |
| Update existing   | `mcp__skynest__update_document`   | `path`, `body`                      |
| Publish/version   | `mcp__skynest__publish_document`  | `path`, `note`                      |
| Audit trail       | `mcp__skynest__verify_integrity`  | —                                   |

## Common Mistakes

- **Not publishing after saving**: Always call `publish_document` after
  create/update or the content won't be visible to AI agents.
- **Wrong selector syntax**: Tags use a `#` prefix (`#project`, not `tag:project`).
- **Skipping vault at session start**: Query first — don't assume you know the
  current state of your documents.
- **Saving code implementations**: The vault is for knowledge, not source code;
  those belong in git.

Activate the skill

Once the file is in place, invoke the skill by typing /skynest in Claude Code. Claude will load the skill and follow its protocol for the rest of the session.

You can also configure the skill's description so that Claude activates it automatically when the session context matches — for example, whenever you start a session related to a project or topic your vault covers.

Customising the template

• Update the vault structure section with your actual nodes/ paths and tags once you've organised your vault.
• Add workflow packs if you create named packs in your vault — call them with mcp__skynest__read_pack({ id: "pack-name", hops: 2 }).
• Extend the common queries section with tag combinations specific to your domain.

Read tools

Write tools — require the mcp:write scope; each write is recorded to the vault-sync backend under your identity

Governance tools

Capture and resolve out-of-band edits through a review workflow without breaking the hash chain.

Required environment variables

Webhook URL

Configure this URL in your read.ai workspace settings:

https://YOUR_SKYNEST_URL/api/webhooks/YOUR_WEBHOOK_API_KEY/default/readai

Replace YOUR_WEBHOOK_API_KEY with the value of your WEBHOOK_API_KEY environment variable. Replace default with your vault ID if you're using a named vault (CONTEXTNEST_DEFAULT_VAULT_ID).

Set the signing key in read.ai to the value of READ_AI_SIGNING_KEY.

What happens on each meeting

1. read.ai POSTs the transcript payload to the webhook URL
2. Skynest verifies the HMAC-SHA256 signature using READ_AI_SIGNING_KEY
3. Deduplication check by request_id (returns 200 immediately if duplicate)
4. Claude Haiku analyzes the meeting: client classification, tags, summary, action items
5. A structured markdown node is written to nodes/meetings/YYYY-MM-DD-slug.md
6. The file is recorded to the configured vault-sync backend under the bot's identity (after the response is sent)