MCP integration¶
Optional Extension. AOS records the MCP server declaration dotagents implements. It does not require a consumer to start the servers an overlay declares, or to run a gateway. A consumer's own MCP server for the overlays' knowledge is another matter, and required.
[mcp]
[[mcp.servers]]
name = "docs"
transport = "stdio"
command = "node"
args = ["server.js"]
env = { MODE = "read-only", DOCS_TOKEN = { provider = "env", key = "DOCS_TOKEN" } }
timeout = 30
[[mcp.servers]]
name = "remote-docs"
transport = "streamable-http"
url = "https://mcp.example.org/agent"
headers_env = { Authorization = "DOCS_AUTHORIZATION" }
[[mcp.skills]]
name = "search-docs"
server = "docs"
Fields and validation¶
mcp holds only servers and skills, both arrays of mappings. Server names are unique within one
overlay, and so are skill names; each matches [A-Za-z0-9][A-Za-z0-9_.-]*.
- Every server has
nameandtransport, and optionally atimeoutin seconds, from 0.001 to 2147483647 (default 60). transport = "stdio"requires a non-emptycommand. Optional:args, an array of strings;env, a mapping of variable name to env value;env_passthrough, unique variable names copied from the consumer's own environment when set.transport = "streamable-http"requires an absolutehttporhttpsurl(scheme in any case) with a host, no user information and no fragment. Optional:headers_env, a mapping of HTTP header name to a variable name whose value, from the consumer's own environment, is sent as that header. Plainhttpto a host other thanlocalhost,127.0.0.0/8or[::1]is the non-default settinginsecure-transport, and a consumer never sends aheaders_envvalue over it unless its policy says so.mcp.skillsentries hold exactlynameandserver. The server MUST be declared in the same overlay, andskills/<name>/SKILL.mdMUST exist.
Proposed: an env value may be any env value, including a path under the
root and a secret reference; dotagents takes strings only. Its text is
substituted against that overlay's environment as the server would
receive it, the entries of one server's env not seeing each other. A stdio server starts with the overlay
root as its working directory, so args = ["server.js"] names the overlay's file; dotagents starts
it in the gateway's own working directory. A command without a separator is found on the base
environment's PATH plus that overlay's own path additions; a
command with a separator is a relative path under the root. On Windows a
command that resolves to a batch file (.cmd, .bat) is refused, as for
interpreters.
env_passthrough and headers_env read the consumer's own environment, and like an env
provider reference they need a grant: a variable not granted is
not passed, and is listed as not granted. Each one passed is the
non-default setting env-passthrough. A literal env value is in the overlay for
anyone to read, so a credential never goes there; a secret reference does.
Starting a stdio server runs the overlay's code, so it is a trust decision like setup. A consumer says whether it runs servers inside the agent's sandbox or outside it, shows each server, its transport and the variables it reads before starting it, and gives it the session's environment.
Gateway behaviour¶
dotagents' optional gateway starts servers when tools are listed, prefixes each server's tools with its name (or a configured namespace), and forwards calls. That gateway and how tools are presented as skills are not part of the declaration. Name collisions and unavailable servers are runtime concerns; see the MCP specification for the protocol.