The Epic Suite
Add a tool to the suite
A tool of your own joins an organisation's suite menu by publishing a manifest at /.well-known/epic-tool.json on its own domain. An owner or admin adds it after seeing what it asks for; it stays on its own domain, its people sign in with Epic Context, and its actions arrive signed.
The suite is open for tools that someone else built: an internal dashboard, a niche app, a service your team relies on. Such a tool does not need Epic Context's code or a shared secret. It describes itself in one JSON file.
The manifest
Publish it at https://<your-tool>/.well-known/epic-tool.json:
{
"id": "acme-reviews",
"name": "Reviews",
"description": "Customer reviews, collected per product.",
"app_name": "Acme Reviews",
"icon": "MessageSquareQuote",
"current": "https://reviews.acme.example/",
"for_ai": "Customer reviews per product. Read them before writing customer insights; ask for a new import with call_tool_action.",
"actions": [
{ "name": "import_reviews", "description": "Import the latest reviews for a product." }
],
"actions_url": "https://reviews.acme.example/epic/actions",
"notifications": [
{ "id": "import_failed", "label": "An import failed", "to": "who started it" }
]
}
| Field | Required | What it is |
|---|---|---|
id | yes | Lowercase letters, digits and hyphens. May not be the id of a built-in tool |
name | yes | The label in the menu, at most 40 characters |
description | yes | One line, at most 240 characters |
app_name | yes | The app behind it, shown on the consent screen (at most 60) |
icon | yes | A Lucide icon name for the menu |
current | yes | Where the tool opens: an https address on the same origin as the manifest |
for_ai | no | One sentence for an AI: when work goes here, and with which verb (at most 300) |
actions | no | Actions AI sessions may call, each with a name and a description |
actions_url | with actions | Where Epic Context posts an action; https, same origin as the manifest |
events, notifications, widgets, settings, settings_pages, theme, count | no | What it emits, the notifications it sends, dashboard cards, settings it reads, its pages in the settings menu, its colour and the number on its icon |
What is checked
- The manifest is fetched over
httpsonly, without following redirects, with a five-second timeout and a 64 KB limit. Private addresses and.localor.internalhosts are refused. currentandactions_urlmust be on the manifest's own origin.- A tool that declares actions must give an
actions_url.
Adding it
An owner or admin opens Settings › Organisation › Apps, enters the tool's address under Add your own app, and sees a consent screen first: where it opens, that people sign in there with their Epic Context account, which actions AI sessions may call, what it wants to hear about and which widgets it offers. On confirm the tool joins the menu, at the end, and Epic Context shows a signing secret once. Removing the tool takes it out of the menu and stops every action at once.
Signing people in
Your tool signs people in with their Epic Context account over OpenID Connect. Discovery is at https://www.epiccontext.com/.well-known/openid-configuration; register your client with dynamic client registration (/oauth/register) and request the openid scope. The ID token tells you who the person is.
Receiving an action
When an AI session calls one of your actions with call_tool_action, Epic Context posts JSON to your actions_url:
{
"action": "import_reviews",
"args": { "product": "…" },
"reason": "The persona needs the latest review themes.",
"organization": { "id": "…", "slug": "…", "name": "…" },
"user": { "id": "…", "email": "…", "name": "…" },
"role": "member"
}
The request carries X-Epic-Signature: t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256 of <t>.<raw body>, keyed with the signing secret exactly as it was shown. Reject a signature older than five minutes. Answer with JSON within fifteen seconds; your answer goes back to the AI session.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyEpicSignature(secret: string, rawBody: string, header: string): boolean {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
const t = Number(parts.t);
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300 || !parts.v1) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
Next
- Plans, hand-offs and notes: what AI sessions do with the actions they find.
- Connecting to the brain: connectors for outside APIs, episodes and webhooks.
- API overview and authentication
Last updated: