A Futurity plugin publishes one manifest at GET /.well-known/futurity/plugin.
It is shaped like an MCP Registry server.json, with everything Futurity needs
under one _meta key, work.futurity/plugin. The manifest is plain JSON with no
signature: Futurity pins the content an admin approved, and any later change
waits as a pending revision until an admin approves it.
@futurity/plugin-manifest is the only validator. The SDK, the platform and the
marketplace all call parsePluginManifest, so every rule below holds wherever a
manifest is read.
type PluginManifest = {
name: string; // reverse-DNS id, e.g. "work.futurity/esb"
title: string;
description: string;
version: string; // semver x.y.z
icons?: { src: string; mimeType?: string; sizes?: string[] }[];
websiteUrl?: string;
remotes: [{ type: "streamable-http"; url: string }]; // exactly one; url may contain {fieldKey}
_meta: { "work.futurity/plugin": FuturityExtension };
};
type FuturityExtension = {
specVersion: 5;
developer: { name?: string; email: string };
category?: string;
listing?: {
tagline?: string;
overview?: string;
features?: { title: string; description: string }[];
links?: { docs?: string; privacy?: string };
};
credentials: CredentialOption[]; // at least one; an admin picks one per org at install
};
type CredentialOption = {
id: string; // unique within the manifest
label: string;
holder: "org" | "user" | "plugin" | "none";
method: OAuthMethod | { type: "secrets" } | { type: "none" };
fields: CredentialField[];
setupSteps?: string[]; // admin instructions shown at install, in order
};
type CredentialField = {
key: string; // unique within the option
label: string;
description?: string;
kind: "setup" | "futurity_secret" | "plugin_secret";
scope: "install" | "connect"; // install = once by an org admin; connect = by each holder
input: "text" | "password" | "textarea" | "x509-keypair";
secondaryKey?: string; // x509-keypair only
required?: boolean; // default true
default?: string;
choices?: string[];
placeholder?: string; // display hint inside an empty input
help?: string; // display hint below the input
header?: string; // delivery header; required for plugin_secret, optional for setup
};
type OAuthMethod = {
type: "oauth";
grant: "authorization_code" | "client_credentials" | "jwt_bearer" | "saml_bearer";
authorizationUrl?: string; // authorization_code only
tokenUrl: string;
scopes?: string[];
authParams?: Record<string, string>;
tokenParams?: Record<string, string>;
actsAs?: "user"; // jwt_bearer and saml_bearer only
client: "futurity" | "install" | "dcr";
delivery: { header: string } | "mcp_authorization";
tokenRequest?: { encoding: "form" | "json" }; // token endpoint body; default "form"
tokenResponseFields?: { key: string; path: string; header: string }[];
callbackQueryFields?: { key: string; param: string; header: string }[]; // authorization_code only
pkce?: boolean; // authorization_code only; default true
};Unknown keys inside the Futurity extension are errors, so a retired key such as
dangerLevel fails loudly. Unknown keys at the top level and in _meta are
dropped, so a full server.json parses.
holdersays whose credential a call uses: the org's, the calling user's, the plugin's own account (plugin, treated likeorgfor availability), or none.methodsays how Futurity gets it: an OAuth exchange Futurity runs, secrets an admin or user types in, or nothing.kindsays where a field's value goes.setupvalues (a tenant, a region) are delivered to the plugin when the field has aheader; asetupfield without a header (an OAuthclient_id, a value onlytokenParamsuses) is used only by Futurity, to fill placeholders,authParamsandtokenParams, and never reaches the plugin.plugin_secretvalues (an API key) are always delivered to the plugin.futurity_secretvalues (a client secret, a private key) stay in Futurity and are used only for the OAuth exchange.
Every parse enforces all of these.
holder: "none"andholder: "plugin"requiremethod: { type: "none" }.method: noneallows onlysetupfields, so a none or plugin holder carries no secrets.method: secretsneeds at least oneplugin_secretfield.method: oauthforbidsplugin_secretfields.client: "install"needs an install-scopedsetupfieldclient_idand an install-scopedfuturity_secretfieldclient_secret. Onjwt_bearerandsaml_bearerit needs instead an install-scopedfuturity_secretprivate key: a field with keyprivate_keyor inputx509-keypair.holder: "org"forbidsscope: "connect"fields.holder: "user"with an OAuth grant other thanauthorization_coderequiresactsAs: "user".actsAsis allowed only onjwt_bearerandsaml_bearer, so a user-heldclient_credentialsoption is rejected.delivery: "mcp_authorization"takes any client:dcrwhen the vendor's authorization server registers clients dynamically,futurityorinstallwhen it does not. Aninstallclient still needs the fields of rule 5.- Every
{fieldKey}placeholder intokenUrl,authorizationUrl,authParamsortokenParamsnames asetupfield withscope: "install"in the same option. A placeholder in the remote URL must name such a field in every option, because an admin may install any of them. Aconnectfield is typed by each member, so it can never choose where org secrets are sent. plugin_secretfields need aheader; asetupfield may have one. Every header matches^X-[A-Za-z0-9-]+$. Afuturity_secretfield takes no header. An OAuthdelivery.header, eachtokenResponseFields[].headerand eachcallbackQueryFields[].headerfollow the same pattern. Headers are unique within an option across fields, the delivery header, token response fields and callback query fields, compared without case.Authorizationis reserved for the Futurity identity token.- URLs (remote, icons, website, links, OAuth endpoints) use https. With
{ development: true },http://localhost,http://127.0.0.1andhttp://[::1]are also accepted. A URL's scheme must be literal, but its host may be an install-time placeholder set by an org admin, sohttps://{tenant}.example.compasses and{base}/mcpdoes not; the platform checks the URL again after it fills the placeholders. authorization_codeneeds anauthorizationUrl, and other grants take none.x509-keypairfields need asecondaryKey; other inputs take none. Keys, including secondary keys, are unique within an option. Option ids are unique within the manifest.pkceis allowed only onauthorization_code. Futurity uses PKCE (S256) unlesspkceisfalse, for providers that reject it.tokenResponseFieldsrequiredelivery: { header }; a vendor server onmcp_authorizationgets nothing from Futurity. Eachpathis a dotted path of property names into the token response JSON (instance_url,team.id). Eachkeyis unique within the option, across field keys, secondary keys and callback query field keys.callbackQueryFieldsare values Futurity copies from the query string of the authorization redirect, such as QuickBooksrealmId. Eachparamis the query parameter name. They are allowed only with theauthorization_codegrant and requiredelivery: { header }. Eachkeyis unique within the option, across field keys, secondary keys and token response field keys.tokenRequest.encodingisform(application/x-www-form-urlencoded, the default) orjson(application/json), the body Futurity sends totokenUrlfor the grant and for refreshes.placeholder,helpandsetupStepsare display hints with no effect on validation or delivery.setupSteps, when present, holds at least one non-empty step.namematches^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$,versionisx.y.z,remotesholds exactly onestreamable-httpremote, andcredentialsholds at least one option.
An org install exists when any field has scope: "install" or the OAuth client
is install; installRequired(option) answers that.
Every call to /mcp carries:
Authorization: Bearer <jwt>, signed by Futurity with the key published at/oauth/jwks. Claims:iss(the Futurity API origin),aud(the remote URL exactly as written in the manifest, placeholders included, never the resolved URL),sub(user id),org_id,holder,credential_option,iat,exp(at most five minutes afteriat) andjti.- One header per
setupandplugin_secretfield of the chosen option that declares aheader. - For OAuth with
delivery: { header }, the access token in that header, and one header pertokenResponseFieldsentry carrying the value Futurity read atpathfrom the token response (for example Salesforceinstance_url), and one header percallbackQueryFieldsentry carrying the value Futurity read fromparamon the authorization redirect (for example QuickBooksrealmId). The SDK requires each of these headers and exposes the values inctx.credentialsunderkey, besideaccess_token.
Setup fields without a header are never delivered.
A server with delivery: "mcp_authorization" is a vendor MCP server. It gets the
vendor's OAuth token in Authorization per the MCP spec and no Futurity token.
Futurity reads the server's protected resource metadata (RFC 9728) and its
authorization server's metadata (RFC 8414), and authorizes, exchanges and
refreshes at the endpoints that metadata names, sending the server's resource
(RFC 8707). A server that publishes no authorization server metadata is reached
at the option's authorizationUrl and tokenUrl. When the option declares no
scopes, Futurity asks for the scopes the protected resource metadata lists.
FuturityIdentityClaimsSchema validates the claims. The SDK trusts a list of
issuers, each with its own JWKS URL (futurity: { issuers: [{ issuer, jwksUrl }] }),
so one plugin deployment can serve production, staging and dev. An issuer such
as https://*.futurity.work with jwksUrl: "/oauth/jwks" trusts every subdomain
origin and fetches its keys from that origin. It picks the
JWKS by the token's iss, refuses any other issuer, verifies the signature,
issuer and audience with jose, and checks that credential_option names an
option in the manifest whose holder matches the token's. Any of those
failing is a 401. A required header of that option that is missing is a 400
missing_credential. It then hands handlers
{ issuer, org, user, holder, credentials, signal }. The SDK does not track
jti, so a replayed token is accepted until it expires.
The iss of each Futurity deployment:
| Deployment | iss |
JWKS |
|---|---|---|
| Production | https://api-v4.futurity.work |
https://api-v4.futurity.work/oauth/jwks |
| Staging | https://api-v4-staging.futurity.work |
https://api-v4-staging.futurity.work/oauth/jwks |
| Local development | http://localhost:4000 |
http://localhost:4000/oauth/jwks |
A self-hosted deployment issues tokens from its own API_URL origin.
client: "futurity"uses an OAuth client Futurity's platform admins register for a marketplace plugin. It only works for plugins in the Futurity marketplace; an org-registered plugin with it fails at connect.client: "install"uses the organization's own client, entered at install as theclient_idandclient_secretfields (rule 5). Use it for a plugin your organization registers.client: "dcr"registers a client once with the server's authorization server through MCP dynamic client registration, when the plugin is registered. It is supported forholder: "user"; an org-helddcroption is not supported yet.
A vendor server whose authorization server offers no dynamic registration
still works with delivery: "mcp_authorization": a marketplace entry uses
client: "futurity" with the client Futurity registered with the vendor (for
example GitHub's MCP server), and an organization that registers the server
itself uses client: "install" with its own OAuth app.
jwt_bearer (RFC 7523) and saml_bearer (RFC 7522) are signed by Futurity
with the install's private key (a futurity_secret field keyed private_key,
or an x509-keypair field). Futurity reads these install setup field keys by
name, so declare them with exactly these keys when the provider needs them:
| Field key | Used for | When absent |
|---|---|---|
client_id |
The JWT iss and the client_id sent with the token request; for SAML, the API key sent as client_id |
Empty |
subject |
The assertion subject when actsAs is not "user" |
client_id |
saml_issuer |
The SAML assertion Issuer (saml_bearer only) |
The Futurity API origin |
saml_audience |
The SAML assertion Audience (saml_bearer only) |
tokenUrl |
With actsAs: "user", the subject is the calling member's email address. A
saml_bearer option needs an x509-keypair field, because the assertion
carries the certificate (secondaryKey). The JWT audience is always the filled
tokenUrl.
Futurity reads danger from standard MCP tool annotations only, through
toolDanger(annotations):
readOnlyHint: trueisread.- otherwise
destructiveHint: trueisdelete. - anything else is
write.
Admins set allow, ask or block per group and per tool.
The manifest does not carry tools. @futurity/plugins requires every tool to
declare output, and advertises it as outputSchema in tools/list.
A third-party MCP server may leave outputSchema out. Futurity connects it all
the same and shows the tool as "Returns: not declared", since it cannot tell
what the tool returns.
import {
parsePluginManifest, // (json, { development? }) => { success, manifest } | { success, errors }
PluginManifestSchema, // production rules
DevelopmentPluginManifestSchema,
FuturityExtensionSchema,
CredentialOptionSchema,
CredentialFieldSchema,
OAuthMethodSchema,
FuturityIdentityClaimsSchema,
FUTURITY_META_KEY, // "work.futurity/plugin"
futurityExtension, // manifest => its _meta extension
installRequired, // option => boolean
fieldsFor, // (option, scope) => fields entered at that step
placeholders, // text => distinct {fieldKey} names
toolDanger, // annotations => "read" | "write" | "delete"
} from "@futurity/plugin-manifest";Errors read as a path and a message, for example
_meta["work.futurity/plugin"].credentials[0].fields[1].header: a plugin_secret field needs a delivery header.
{
"name": "work.futurity/esb",
"title": "ESB Core",
"description": "Sales, stock and outlets from ESB Core",
"version": "1.0.0",
"remotes": [{ "type": "streamable-http", "url": "https://esb.plugins.futurity.work/mcp" }],
"_meta": {
"work.futurity/plugin": {
"specVersion": 5,
"developer": { "email": "plugins@futurity.work" },
"credentials": [
{
"id": "company-key",
"label": "Company API key",
"holder": "org",
"method": { "type": "secrets" },
"fields": [
{ "key": "company_code", "label": "Company code", "kind": "setup", "scope": "install", "input": "text", "header": "X-Company-Code" },
{ "key": "api_key", "label": "API key", "kind": "plugin_secret", "scope": "install", "input": "password", "header": "X-Api-Key" }
]
}
]
}
}
}An OAuth option that reads a value from the token response, and one that sends a JSON token body with PKCE off and an admin-entered client:
[
{
"id": "salesforce-user",
"label": "Sign in with Salesforce",
"holder": "user",
"method": {
"type": "oauth",
"grant": "authorization_code",
"authorizationUrl": "https://login.salesforce.com/services/oauth2/authorize",
"tokenUrl": "https://login.salesforce.com/services/oauth2/token",
"client": "futurity",
"delivery": { "header": "X-Salesforce-Token" },
"tokenResponseFields": [{ "key": "instance_url", "path": "instance_url", "header": "X-Instance-Url" }]
},
"fields": []
},
{
"id": "lark-app",
"label": "Your Lark app",
"holder": "user",
"setupSteps": ["Create a custom app in the Lark developer console", "Paste its App ID and App Secret below"],
"method": {
"type": "oauth",
"grant": "authorization_code",
"authorizationUrl": "https://open.larksuite.com/open-apis/authen/v1/authorize",
"tokenUrl": "https://open.larksuite.com/open-apis/authen/v2/oauth/token",
"client": "install",
"delivery": { "header": "X-Lark-Token" },
"tokenRequest": { "encoding": "json" },
"pkce": false
},
"fields": [
{ "key": "client_id", "label": "App ID", "kind": "setup", "scope": "install", "input": "text", "placeholder": "cli_a1b2c3" },
{ "key": "client_secret", "label": "App Secret", "kind": "futurity_secret", "scope": "install", "input": "password" }
]
}
]