Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.
JavaScript agentagentsai-agentdeepagentsdesignhyperframeslanggraphmanaged-agentsmotion-graphicspaperslackvideo
Integrations: presets for nine hosted MCP servers, and connections that belong to each person (#22)
Amal Irgashevb39fa3302e12
diff --git a/.agents/skills/design-agent-customize/SKILL.md b/.agents/skills/design-agent-customize/SKILL.mdindex 0c7e1fa..8b49b38 100644--- a/.agents/skills/design-agent-customize/SKILL.md+++ b/.agents/skills/design-agent-customize/SKILL.md@@ -50,7 +50,9 @@ sibling skill of ours, or send the change upstream.- **MCP servers:** copy `config/mcp.example.toml` to `config/mcp.toml` and declare servers. Locally,header values come from the environment (`headers_env`); on MDA a server that needs credentials- names a workspace connection (`connection`). MDA serves HTTP and SSE only. Paper is configured+ names a workspace connection (`connection`), owned by the deployment or each person (`owner`).+ The example file has presets for Notion, Linear, GitHub, Figma and others+ ([integrations](../../../docs/integrations.md)). MDA serves HTTP and SSE only. Paper is configuredwith `PAPER_*`, not here ([Paper](../../../docs/partners/paper.md)).- **Media keys:** `OPENAI_API_KEY` (images), `ELEVENLABS_API_KEY` (voice, music, sound effects),`GROQ_API_KEY` (transcription).diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 885889b..fd3c8db 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,13 @@## Unreleased+### Added++- Integrations: `config/mcp.example.toml` has ready entries for the official MCP servers of+ Notion, Linear, GitHub, Figma, Atlassian, Asana, Canva, Webflow and Box, and a server's+ connection can belong to each person (`owner = "user"`), so MDA asks whoever has not connected+ to sign in with a link and the agent then acts as them. `docs/integrations.md` sets each up.+### Changed- A plain `mda deploy` deploys the project, and `mda dev` runs it: vendored skills' binary filesdiff --git a/config/mcp.example.toml b/config/mcp.example.tomlindex 351b794..33e5ba8 100644--- a/config/mcp.example.toml+++ b/config/mcp.example.toml@@ -1,12 +1,84 @@# MCP servers the agent may use, on every runtime (src/design_agent/tools/mcp.py). Copy to-# config/mcp.toml (Git-ignored) and uncomment.+# config/mcp.toml (Git-ignored) and uncomment what you want. docs/integrations.md walks through it.# Names are lowercase letters and digits; tools are named `{server}_{tool}`.-# Header values come from the host environment by name and never enter the sandbox.#+# On Managed Deep Agents a server signs in through a workspace connection (`connection`):+# owner = "user" each person signs in to their own account the first time a request needs it+# (MDA posts a connect link). Create the connection once with+# `uv run mda connections create <connection> --mcp <url>`.+# owner = "agent" one account for everyone. Create it and sign in now with+# `uv run mda connections create <connection> --mcp <url> --authorize`.+# Locally and self-hosted, a server sends headers read from the host environment (`headers_env`)+# instead, and per-person servers are left out. Header values never enter the sandbox.++# --- Hosted integrations (official MCP servers, OAuth) ------------------------------------------++# Notion: pages, databases and comments (briefs, launch docs, content calendars).+# [servers.notion]+# url = "https://mcp.notion.com/mcp"+# connection = "notion"+# owner = "user"++# Linear: issues, projects and comments (design requests, specs).+# [servers.linear]+# url = "https://mcp.linear.app/mcp"+# connection = "linear"+# owner = "user"++# GitHub: repositories, pull requests and issues (release notes, PR explainers).+# Locally, a personal access token works too: headers_env = { Authorization = "GITHUB_MCP_AUTHORIZATION" }+# with GITHUB_MCP_AUTHORIZATION="Bearer <token>".+# [servers.github]+# url = "https://api.githubcopilot.com/mcp/"+# connection = "github"+# owner = "user"++# Figma: frames, components and variables from design files. Figma admits only clients in its MCP+# catalog to the remote server; check yours is listed.+# [servers.figma]+# url = "https://mcp.figma.com/mcp"+# connection = "figma"+# owner = "user"++# Atlassian: Jira issues and Confluence pages (Cloud only).+# [servers.atlassian]+# url = "https://mcp.atlassian.com/v1/mcp"+# connection = "atlassian"+# owner = "user"++# Asana: tasks and projects. Asana's v2 server takes only clients registered in its developer+# console, not automatic registration, so its connection needs a registered client first.+# [servers.asana]+# url = "https://mcp.asana.com/v2/mcp"+# connection = "asana"+# owner = "user"++# Canva: designs and brand assets. Access to Canva's server is limited; check it is open to you.+# [servers.canva]+# url = "https://mcp.canva.com/mcp"+# connection = "canva"+# owner = "user"++# Webflow: sites, CMS collections and pages.+# [servers.webflow]+# url = "https://mcp.webflow.com/mcp"+# connection = "webflow"+# owner = "user"++# Box: files and folders a person can already open. A Box admin enables MCP first.+# [servers.box]+# url = "https://mcp.box.com"+# connection = "box"+# owner = "user"++# --- Your own servers ---------------------------------------------------------------------------++# A server of your own, read-only docs search with a shared token:# [servers.docs]# url = "https://docs.example.com/mcp"-# transport = "http"-# headers_env = { Authorization = "DOCS_MCP_AUTHORIZATION" }+# transport = "http" # or "sse"+# connection = "docs-token" # MDA: a workspace connection holding its credentials+# headers_env = { Authorization = "DOCS_MCP_AUTHORIZATION" } # local and self-hosted# include_tools = ["search"]# timeout = 30# always_shown = falsediff --git a/docs/README.md b/docs/README.mdindex ea03936..4109ced 100644--- a/docs/README.md+++ b/docs/README.md@@ -12,6 +12,7 @@ which one fits.| [CLI](cli.md) | every `design-agent` command || [Models](models.md) | providers, the LangSmith Gateway, roles, effort, cost || [Customization](customization.md) | brand packs, instructions, runtime skills, learning, MCP servers |+| [Integrations](integrations.md) | Notion, Linear, GitHub, Figma and other MCP servers, per person or shared || [Paper](partners/paper.md) | the shared canvas: local, bridged and off || [HyperFrames](partners/hyperframes.md) | the video engine and its vendored skills |diff --git a/docs/customization.md b/docs/customization.mdindex c676f62..0461458 100644--- a/docs/customization.md+++ b/docs/customization.md@@ -48,10 +48,12 @@ where people must not see each other's requests ([SECURITY.md](../SECURITY.md#tr## MCP servers-Copy `config/mcp.example.toml` to `config/mcp.toml` and declare servers there. Every runtime names+[Integrations](integrations.md) sets up the hosted ones (Notion, Linear, GitHub, Figma and more) in+a few commands. Copy `config/mcp.example.toml` to `config/mcp.toml` and declare servers there. Every runtime namestheir tools `{server}_{tool}`; the agent discovers them on demand, so many servers do not crowd itscontext. Locally, header values come from your environment (`headers_env`); on MDA a server that-needs credentials names a workspace connection (`connection`). A local app's own server can run+needs credentials names a workspace connection (`connection`), owned by the deployment or by each+person (`owner`). A local app's own server can runover stdio (`transport = "stdio"` with a `command`) locally and self-hosted; MDA serves HTTP and SSEonly and leaves it out. A server that fails to load or errors leaves the rest working. Paper isconfigured with `PAPER_*` instead ([Paper](partners/paper.md)), so do not declare a `paper` server.diff --git a/docs/integrations.md b/docs/integrations.mdnew file mode 100644index 0000000..68814fb--- /dev/null+++ b/docs/integrations.md@@ -0,0 +1,78 @@+# Integrations++The agent reaches other tools through MCP servers: Notion for a brief, Linear for the request+behind it, Figma for the frames, GitHub for the pull request a video explains. Each server's tools+are named `{server}_{tool}` and found through tool search, so a dozen servers do not crowd the+agent's context, and one that fails to load leaves the rest working. What a server returns is+treated as untrusted input, like any file someone attaches.++`config/mcp.example.toml` has ready entries for the services below. Copy it to `config/mcp.toml`+(Git-ignored) and uncomment the ones you want.++## On Managed Deep Agents++Every hosted server here signs in with OAuth through a workspace connection. Choose who it signs+in as with `owner`.++**Each person's own account** (`owner = "user"`, the preset's default). The agent acts as whoever+asked, so it sees only what they can see.++```bash+uv run mda connections create notion --mcp https://mcp.notion.com/mcp+uv run mda deploy+```++The first time a person's request needs Notion, MDA's credential gate stops the run before it+starts and posts a connect link. They sign in once, and the next request goes through. Runs started+with an API key have no person to sign in, so they end with sign-in guidance instead.++**One shared account** (`owner = "agent"`). Everyone's requests use the account that signs in when+the connection is created:++```bash+uv run mda connections create notion --mcp https://mcp.notion.com/mcp --authorize+```++Anyone who can mention the agent can then read what that account can, so give it a workspace or+teamspace made for the agent, and narrow its tools with `include_tools`.++`uv run mda connections list` shows what exists. The connection name in `mcp.toml` must match the+one you create.++## The presets++| Service | Server | Good for | Before you start |+| --- | --- | --- | --- |+| Notion | `https://mcp.notion.com/mcp` | Briefs, launch docs, content calendars | |+| Linear | `https://mcp.linear.app/mcp` | Design requests and specs in issues | |+| GitHub | `https://api.githubcopilot.com/mcp/` | Pull requests and release notes for explainers | |+| Figma | `https://mcp.figma.com/mcp` | Frames, components and variables | Figma admits only clients in its MCP catalog |+| Atlassian | `https://mcp.atlassian.com/v1/mcp` | Jira issues and Confluence pages | Cloud sites only |+| Asana | `https://mcp.asana.com/v2/mcp` | Tasks and projects | Needs a client registered in Asana's developer console |+| Canva | `https://mcp.canva.com/mcp` | Designs and brand assets | Access is limited; check it is open to you |+| Webflow | `https://mcp.webflow.com/mcp` | Sites, CMS collections and pages | |+| Box | `https://mcp.box.com` | Files a person can already open | A Box admin enables MCP first |++Each provider runs its own server and can change it; if one stops connecting, check its docs for+the current address.++## Locally and self-hosted++Per-person connections exist only on MDA, so `owner = "user"` servers are left out locally and+self-hosted, with a warning. For a shared account there, send a token from the host environment:++```toml+[servers.github]+url = "https://api.githubcopilot.com/mcp/"+headers_env = { Authorization = "GITHUB_MCP_AUTHORIZATION" }+```++with `GITHUB_MCP_AUTHORIZATION="Bearer <token>"` in `.env`. Header values never reach the sandbox.++## Your own server++Any HTTP or SSE MCP server works the same way; `config/mcp.example.toml` ends with a template. A+local app's stdio server (`transport = "stdio"`) runs locally and self-hosted only. Paper is set up+with `PAPER_*` instead ([Paper](partners/paper.md)).++`uv run design-agent doctor` lists the servers this checkout declares.diff --git a/src/design_agent/tools/mcp.py b/src/design_agent/tools/mcp.pyindex df75a4f..f14182f 100644--- a/src/design_agent/tools/mcp.py+++ b/src/design_agent/tools/mcp.py@@ -7,7 +7,8 @@ and `servers_for_runtime` returns both:url = "https://docs.example.com/mcp"transport = "http" # or "sse"; "stdio" with `command` instead of `url`headers_env = { Authorization = "DOCS_MCP_AUTH" } # local/self-hosted: header -> host env var- connection = "docs-token" # MDA: agent-owned workspace connection (Agent Auth)+ connection = "docs-token" # MDA: a workspace connection (Agent Auth)+ owner = "agent" # MDA: "agent" (one shared account) or "user" (each person's own)include_tools = ["search"] # optionaltimeout = 30 # seconds per requestalways_shown = false # keep its schemas bound instead of deferred@@ -26,9 +27,12 @@ Isolation:Credentials stay on the host and out of artifacts. Locally and self-hosted, header values are readfrom the host environment when the server loads (a `bearer` comes from typed settings, masked). OnMDA the declaration is compiled into the deployment, so header values are never put in it: a server-that needs credentials names an agent-owned workspace connection (`connection`), which MDA resolves-at call time; one that names only `headers_env` or a `bearer` is left out on MDA with a warning.-Nothing reaches the sandbox.+that needs credentials names a workspace connection (`connection`), which MDA resolves at call time;+one that names only `headers_env` or a `bearer` is left out on MDA with a warning. A connection is+owned by the deployment (`owner = "agent"`: one account everyone's requests use) or by each person+(`owner = "user"`: MDA's credential gate asks a person who has not connected yet to sign in, with a+connect link, before the run starts). Per-person connections exist only on MDA, so local and+self-hosted runtimes leave those servers out with a warning. Nothing reaches the sandbox.Stdio servers (`transport = "stdio"`, a local app's own CLI) run locally and self-hosted only: MDA's`define_mcp` speaks HTTP and SSE, so they are left out of its declaration with a warning. The child@@ -61,6 +65,7 @@ if TYPE_CHECKING:_LOGGER = logging.getLogger(__name__)SERVER_NAME = re.compile(r"[a-z][a-z0-9]{0,30}")+Owner = Literal["agent", "user"]CONFIG = Path("config") / "mcp.toml"@@ -78,6 +83,8 @@ class McpServer:timeout: float = 30.0always_shown: bool = Falseconnection: str | None = None+ owner: Owner = "agent"+ """Who the connection belongs to on MDA: the deployment, or each person (module doc)."""command: tuple[str, ...] = ()"""A stdio server's executable and arguments (`url` is empty)."""bearer: SecretStr | None = field(default=None, repr=False, compare=False)@@ -115,6 +122,13 @@ def declared_servers(project_root: Path) -> list[McpServer]:f"MCP server {name}: url must be https (or http://127.0.0.1 for a local app)")include = entry.get("include_tools")+ owner = entry.get("owner", "agent")+ if owner not in ("agent", "user"):+ raise McpConfigError(f"MCP server {name}: owner must be agent or user")+ if owner == "user" and not entry.get("connection"):+ raise McpConfigError(+ f'MCP server {name}: owner = "user" needs a connection for each person to sign in to'+ )servers.append(McpServer(name=name,@@ -128,6 +142,7 @@ def declared_servers(project_root: Path) -> list[McpServer]:timeout=float(entry.get("timeout", 30)),always_shown=bool(entry.get("always_shown", False)),connection=str(entry["connection"]) if entry.get("connection") else None,+ owner=owner,))return servers@@ -156,6 +171,14 @@ def servers_for_runtime(from design_agent.tools.paper import SERVER, PaperConfigError, paper_serverservers = declared_servers(project_root)+ if runtime != "mda":+ for server in servers:+ if server.owner == "user":+ _LOGGER.warning(+ "[mcp] %s left out: per-person connections need Managed Deep Agents",+ server.name,+ )+ servers = [server for server in servers if server.owner != "user"]if any(s.name == SERVER for s in servers):raise McpConfigError(f"config/mcp.toml declares `{SERVER}`; Paper is configured with PAPER_MODE instead"@@ -246,7 +269,7 @@ def mda_declaration(servers: Sequence[McpServer]) -> Any:"timeout": server.timeout,}if server.connection is not None:- entry["connection"] = connections.get(server.connection, {"type": "agent"})+ entry["connection"] = connections.get(server.connection, {"type": server.owner})if server.include_tools is not None:entry["include_tools"] = list(server.include_tools)declared[server.name] = entrydiff --git a/tests/unit/test_mcp_integrations.py b/tests/unit/test_mcp_integrations.pynew file mode 100644index 0000000..6cc4c0c--- /dev/null+++ b/tests/unit/test_mcp_integrations.py@@ -0,0 +1,97 @@+"""Integrations: the presets in `config/mcp.example.toml` and per-person connections (`owner`)."""++from __future__ import annotations++import logging+import re+from pathlib import Path+from typing import Any++import pytest++from design_agent.config import Settings+from design_agent.tools import mcp+from design_agent.tools.mcp import (+ McpConfigError,+ McpServer,+ declared_servers,+ mda_declaration,+ servers_for_runtime,+)++ROOT = Path(__file__).resolve().parents[2]+SETTING = re.compile(r"# (\[servers\.[a-z0-9]+\]|[a-z_]+ = .*)$")+++def presets() -> str:+ """The hosted-integration entries of the example file, uncommented."""+ text = (ROOT / "config" / "mcp.example.toml").read_text(encoding="utf-8")+ section = text.split("--- Hosted integrations", 1)[1].split("--- Your own servers", 1)[0]+ return "\n".join(m.group(1) for line in section.splitlines() if (m := SETTING.match(line)))+++def write_config(root: Path, text: str) -> None:+ (root / "config").mkdir(exist_ok=True)+ (root / "config" / "mcp.toml").write_text(text, encoding="utf-8")+++def settings() -> Settings:+ return Settings(_env_file=None) # type: ignore[call-arg]+++def test_every_preset_is_a_valid_per_person_server(tmp_path: Path) -> None:+ write_config(tmp_path, presets())+ servers = declared_servers(tmp_path)+ assert [s.name for s in servers] == [+ "notion",+ "linear",+ "github",+ "figma",+ "atlassian",+ "asana",+ "canva",+ "webflow",+ "box",+ ]+ assert all(s.owner == "user" and s.connection == s.name for s in servers)+ assert all(s.url.startswith("https://") and s.transport == "http" for s in servers)+++def test_owner_is_agent_or_user_and_a_person_needs_a_connection(tmp_path: Path) -> None:+ write_config(tmp_path, '[servers.docs]\nurl = "https://docs.example.com/mcp"\n')+ assert declared_servers(tmp_path)[0].owner == "agent"+ write_config(tmp_path, '[servers.docs]\nurl = "https://d.example/mcp"\nowner = "team"\n')+ with pytest.raises(McpConfigError, match="owner must be agent or user"):+ declared_servers(tmp_path)+ write_config(tmp_path, '[servers.docs]\nurl = "https://d.example/mcp"\nowner = "user"\n')+ with pytest.raises(McpConfigError, match="needs a connection"):+ declared_servers(tmp_path)+++def test_mda_resolves_each_connection_for_its_owner(monkeypatch: pytest.MonkeyPatch) -> None:+ declared: dict[str, Any] = {}+ monkeypatch.setattr(+ "managed_deepagents.define_mcp", lambda **config: declared.update(config) or "declared"+ )+ servers = [+ McpServer("notion", "https://mcp.notion.com/mcp", connection="notion", owner="user"),+ McpServer("docs", "https://docs.example.com/mcp", connection="docs"),+ ]+ assert mda_declaration(servers) == "declared"+ owners = {name: entry["connection"].owner for name, entry in declared["servers"].items()}+ assert owners == {"notion": {"type": "user"}, "docs": {"type": "agent"}}+++def test_per_person_servers_run_only_on_mda(+ tmp_path: Path, caplog: pytest.LogCaptureFixture+) -> None:+ write_config(+ tmp_path,+ '[servers.notion]\nurl = "https://mcp.notion.com/mcp"\nconnection = "notion"\n'+ 'owner = "user"\n\n[servers.docs]\nurl = "https://docs.example.com/mcp"\n',+ )+ assert [s.name for s in servers_for_runtime(tmp_path, settings(), "mda")] == ["notion", "docs"]+ with caplog.at_level(logging.WARNING, logger=mcp.__name__):+ local = servers_for_runtime(tmp_path, settings(), "local")+ assert [s.name for s in local] == ["docs"]+ assert "notion left out: per-person connections need Managed Deep Agents" in caplog.text