Skip to content

Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.

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.md
index 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 configured
with `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.md
index 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 files
diff --git a/config/mcp.example.toml b/config/mcp.example.toml
index 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 = false
diff --git a/docs/README.md b/docs/README.md
index 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.md
index 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 names
their tools `{server}_{tool}`; the agent discovers them on demand, so many servers do not crowd its
context. 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 run
over stdio (`transport = "stdio"` with a `command`) locally and self-hosted; MDA serves HTTP and SSE
only and leaves it out. A server that fails to load or errors leaves the rest working. Paper is
configured with `PAPER_*` instead ([Paper](partners/paper.md)), so do not declare a `paper` server.
diff --git a/docs/integrations.md b/docs/integrations.md
new file mode 100644
index 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.py
index 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"] # optional
timeout = 30 # seconds per request
always_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 read
from the host environment when the server loads (a `bearer` comes from typed settings, masked). On
MDA 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.0
always_shown: bool = False
connection: 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_server
servers = 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] = entry
diff --git a/tests/unit/test_mcp_integrations.py b/tests/unit/test_mcp_integrations.py
new file mode 100644
index 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