WhyVault

Other MCP clients

WhyVault is a hosted remote MCP server: one endpoint, Streamable HTTP, OAuth 2.1 – any client that speaks remote MCP can connect.

Any client that supports remote MCP servers can connect to WhyVault. The address is https://mcp.whyvault.io.

  • Transport: Streamable HTTP
  • Sign-in: OAuth 2.1 with authorization code and PKCE (S256)
  • Registration: Dynamic Client Registration (RFC 7591)
  • Without OAuth: clients send an access key from Connect agents as Authorization: Bearer wv_….

The metadata is at /.well-known/oauth-protected-resource on mcp.whyvault.io; without credentials the server answers 401 with a pointer to it. A description of the server (server card) is at https://whyvault.io/.well-known/mcp/server-card.json.

Requirements

  • Remote MCP over Streamable HTTP. Clients that only start local servers (stdio) need a bridge – see stdio-only clients.
  • Either OAuth 2.1 with PKCE and Dynamic Client Registration – the client opens a sign-in window and handles tokens itself –
  • or custom headers, so you can send an access key.
  • WhyVault: any account, Free included. Nothing to install – the server runs hosted, EU-hosted in Frankfurt and GDPR-compliant.

Endpoint and transport

WhatValue
Endpointhttps://mcp.whyvault.io – the root, no path
TransportStreamable HTTP, stateless (every request stands alone)
AuthAuthorization: Bearer … header – OAuth token or wv_… key
Server nameWhyVault

The server is stateless: there's no session to keep alive, so a dropped connection simply continues with the next request. The older HTTP+SSE transport is not offered – if your client asks for a transport type, pick HTTP or Streamable HTTP, not SSE.

How the OAuth sign-in works

Discovery. The client calls the endpoint without a token and gets 401 with WWW-Authenticate: Bearer resource_metadata="…". That document (RFC 9728) names the authorization server.

Registration. The client reads the authorization server's metadata (RFC 8414) and registers itself (RFC 7591). For older clients that look for the metadata on the MCP host, https://mcp.whyvault.io/.well-known/oauth-authorization-server passes it through.

Sign-in and approval. The client opens the authorization URL with PKCE (S256). You sign in to WhyVault and approve on the consent page – it shows the name the client registered.

Tokens. The client exchanges the code for an access token and sends it as a Bearer header with every request. Tokens are short-lived; the client renews them at the token endpoint.

Scopes: don't configure any. The authorization server only knows standard scopes and rejects unknown ones such as vault:read. What a connection may do is set in WhyVault under Connect agents – read, write and, if you allow it, delete.

Permissions decide the tool list

A connection only sees the tools it may use. With read access: vault_overview, search_notes, read_note, list_notes, get_backlinks. With write access, also create_note, append_to_note, update_section and replace_note. delete_note only appears once you allow deleting. Details: MCP tools.

Examples

MCP Inspector – to test whether the connection works:

npx @modelcontextprotocol/inspector --cli https://mcp.whyvault.io --transport http --method tools/list --header "Authorization: Bearer wv_…"

VS Code – in .vscode/mcp.json (note servers and type, unlike Cursor):

.vscode/mcp.json
{
  "servers": {
    "whyvault": {
      "type": "http",
      "url": "https://mcp.whyvault.io",
      "headers": { "Authorization": "Bearer wv_…" }
    }
  }
}

Gemini CLI:

gemini mcp add --transport http whyvault https://mcp.whyvault.io -H "Authorization: Bearer wv_…"

stdio-only clients

Clients that can only start local processes reach WhyVault via the mcp-remote bridge. It handles the OAuth sign-in in the browser:

{
  "mcpServers": {
    "whyvault": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.whyvault.io"]
    }
  }
}

Troubleshooting

404 or "not found"

You added a path. On mcp.whyvault.io only the root answers – https://mcp.whyvault.io/mcp or /sse return 404.

The client tries SSE and fails

Set the transport to HTTP or Streamable HTTP. If the client only knows SSE, use mcp-remote.

invalid_scope during sign-in

The client sends its own scopes. Remove them from the client's configuration – no scopes are needed.

The sign-in window doesn't open

Some clients don't support Dynamic Client Registration or have no browser. Use an access key in the header instead. If the email link opens in a different browser, type the code from the email in the sign-in window.

401 after it worked

The access key or connection was revoked under Connect agents, or the token expired and the client didn't renew it. Sign in again or create a new key.

Write tools are missing

The connection is read only. Change its permissions in WhyVault and reconnect so the client reloads the tool list.

A write fails with "too many changes"

A connection may make up to 30 changes per minute. The tool answers with an error result; wait a minute and bundle changes.

FAQ

Is there a local version?

No. WhyVault runs hosted; for stdio-only clients use mcp-remote.

Which client name appears in my history?

The name the client registered via OAuth, or the name you gave the access key.

Can several clients use the same vault?

Yes – that's the point. Every client gets its own connection with its own permissions, and all of them read and write the same notes.

Next steps

On this page

RequirementsEndpoint and transportHow the OAuth sign-in worksPermissions decide the tool listExamplesstdio-only clientsTroubleshooting404 or "not found"The client tries SSE and failsinvalid_scope during sign-inThe sign-in window doesn't open401 after it workedWrite tools are missingA write fails with "too many changes"FAQIs there a local version?Which client name appears in my history?Can several clients use the same vault?Next steps