MCP Servers and Plugins
PromptScript treats tool integrations as source-controlled agent platform configuration.
@mcpServersdefines project tool servers once.@agents.mcpServersgrants named agents access to selected servers on supporting targets.@pluginsgroups skills, hooks, and MCP servers into reusable capability bundles.
Both blocks require PromptScript syntax 1.4.0.
MCP Servers
Define local stdio servers:
@mcpServers { repository-tools: { transport: "stdio" command: ["node", "./tools/repository-mcp.mjs"] timeoutMs: 30000 }}Define remote HTTP or SSE servers:
@mcpServers { knowledge-base: { transport: "http" url: "https://mcp.example.com/api" headers: { X-Client: "promptscript" } }}MCP Properties
| Property | Purpose |
|---|---|
transport | stdio, http, or sse |
command | Executable and argument array for stdio servers |
url | Endpoint for HTTP and SSE servers |
env | Environment variables or environment references |
headers | HTTP request headers |
disabled | Disable a server without removing its definition |
enabledTools | Restrict enabled tools |
disabledTools | Disable selected tools |
timeoutMs | Configure startup or request timeout |
Target formatters translate these properties into native MCP configuration. File paths and supported
fields vary by platform, and some targets write MCP config only in full mode. A target or mode
without MCP output reports PS4002. See the formatter capability matrix.
Credential Handling
Do not store tokens in .prs files or generated MCP configuration. Provide credentials through the
target platform’s runtime environment or native secret management. Generated MCP files are
platform-specific, so review output for every enabled target before enabling a server in production.
Agent-Level Access
Agents reference top-level servers by name:
@agents { incident-responder: { description: "Investigate incidents using observability data" mcpServers: ["observability", "issue-tracker"] content: "Collect evidence, identify impact, and prepare remediation." }}Platforms without agent-level MCP fields continue using project-level server configuration.
Plugins
Plugins group related capabilities:
@plugins { security-suite: { description: "Security review capabilities" version: "1.0.0" skills: ["security-review", "threat-model"] hooks: ["validate-generated-files"] mcpServers: ["vulnerability-database"] }}| Property | Purpose |
|---|---|
description | Human-readable bundle purpose |
version | Semantic bundle version |
skills | Referenced skill names |
hooks | Referenced lifecycle hook IDs |
mcpServers | Referenced MCP server names |
Current plugin output exists for Factory, Cursor, Codex, and Grok target families. Cursor and Grok
write it only in full mode, Factory and Codex in multifile and full. Other targets and modes
report PS4002 and omit @plugins. Plugin contracts
are platform-specific, so target support must be checked before using a generated manifest.
Marketplace discovery, installation, and publishing remain outside compiler scope.
Enterprise Policy
Recommended controls:
- Keep MCP and plugin definitions in reviewed source.
- Provide credentials through the target runtime rather than source files.
- Restrict MCP domains and executable paths in organization policy.
- Pin imported capability bundles through
promptscript.lock. - Review generated configuration changes in pull requests.
- Run strict validation and security scanning in CI.