Skip to content

MCP Servers and Plugins

PromptScript treats tool integrations as source-controlled agent platform configuration.

  • @mcpServers defines project tool servers once.
  • @agents.mcpServers grants named agents access to selected servers on supporting targets.
  • @plugins groups 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
}
}
Try in Playground

Define remote HTTP or SSE servers:

@mcpServers {
knowledge-base: {
transport: "http"
url: "https://mcp.example.com/api"
headers: {
X-Client: "promptscript"
}
}
}
Try in Playground

MCP Properties

PropertyPurpose
transportstdio, http, or sse
commandExecutable and argument array for stdio servers
urlEndpoint for HTTP and SSE servers
envEnvironment variables or environment references
headersHTTP request headers
disabledDisable a server without removing its definition
enabledToolsRestrict enabled tools
disabledToolsDisable selected tools
timeoutMsConfigure 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."
}
}
Try in Playground

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"]
}
}
Try in Playground
PropertyPurpose
descriptionHuman-readable bundle purpose
versionSemantic bundle version
skillsReferenced skill names
hooksReferenced lifecycle hook IDs
mcpServersReferenced 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:

  1. Keep MCP and plugin definitions in reviewed source.
  2. Provide credentials through the target runtime rather than source files.
  3. Restrict MCP domains and executable paths in organization policy.
  4. Pin imported capability bundles through promptscript.lock.
  5. Review generated configuration changes in pull requests.
  6. Run strict validation and security scanning in CI.