An 8-bit style icon shows two interlocking shapes—a script file with brackets and prompt arrow on one side and a server block on the other, connected by lines signifying protocols. Five vivid colored circles and squares represent resource blocks and parameters between the shapes. A cloud and gear icon suggest remote access and configurable tools. All elements are geometric, with no background, text, or people, and use only five bold corporate colors.

Model Context Protocol Server

The Model Context Protocol (MCP) defines a protocol that allows to share tools and consume them regardless of the underlying framework/runtime.

GenAIScript implements a server that turns scripts into MCP tools.

Scripts as MCP Tools

GenAIScript launches a MCP server that exposes each GenAIScript script as a MCP tool (not to be confused with defTool).

The MCP tool description is the script description. Make sure to carefully craft the description as it is how the LLM decides which tool to use when running a script. If your tool does not get picked up by the LLM, it’s probably a description issue.

The MCP tool parameters is inferred from the script parameters and files automatically. The MCP parameters will then populate the env.vars object in the script as usual.

The MCP tool output is the script output. That is, typically, the last assistant message for a script that uses the top-level context. Or any content that was passed in env.output.

Let’s see an example. Here is a script task.genai.mjs that takes a task parameter input, builds a prompt and the LLM output is sent back.

script({
    description: "You MUST provide a description!",
    parameters: {
        task: {
            type: "string",
            description: "The task to perform",
            required: true
        }
    }
})

const { task } = env.vars // extract the task parameter

... // genaiscript logic
$`... prompt ... ${task}` // output the result

A more advanced script might not use the top-level context and instead use the env.output to pass the result.

script({
    description: "You MUST provide a description!",
    accept: "none", // this script does not use 'env.files'
    parameters: {
        task: {
            type: "string",
            description: "The task to perform",
            required: true
        }
    }
})

const { output } = env // store the output builder
const { task } = env.vars // extract the task parameter

... // genaiscript logic with inline prompts
const res = runPrompt(_ => `... prompt ... ${task}`) // run some inner the prompt
...

// build the output
output.fence(`The result is ${res.text}`)

Sampling

Clients that support Sampling will allow servers to request completions from LLMs. Recently, Visual Studio Code Copilot Chat has added support for MCP tools sampling.

In GenAIScript script, you can use the mcp llm provider to explicitly use the MCP tool sampling.

script({ model: "mcp:claude" });

The model name (claude) is a hint for the client which LLM to use for sampling. It is just a hint and the client may decide to use a different LLM. This provider is only available when the script is run as a MCP tool with a client that supports sampling.

Annotations

Tool annotations provide additional metadata about a tool’s behavior, helping clients understand how to present and manage tools. These annotations are hints that describe the nature and impact of a tool, but should not be relied upon for security decisions.

script({
    ...,
    annotations: {
        readOnlyHint: true,
        openWorldHint: true,
    },
})

title is populated from the script title.
readOnlyHint: boolean, default: false
If true, indicates the tool does not modify its environment.
destructiveHint: boolean, default: true
If true, the tool may perform destructive updates (only meaningful when readOnlyHint is false).
idempotentHint: boolean, default: false
If true, calling the tool repeatedly with the same arguments has no additional effect (only meaningful when readOnlyHint is false).
openWorldHint: boolean, default: true
If true, the tool may interact with an “open world” of external entities.

Resources

Resources are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data and content that can be read by clients and used as context for LLM interactions.

In GenAIScript, you can create a resource using host.publishResource and it will automatically be exposed as a MCP resource.

const id = await host.publishResource("important data", file);

The return value is the resource uri which can be used in the prompt output. publishResource supports files, buffers and strings.

The resource will be available for the lifetime of the MCP server.

Images

Using env.output.image, script can output images that will be part of the tool response.

await env.output.image("...filename.png");

Secret scanning

GenAIScript has a built-in secret scanning feature that will scan your resources for secrets. To turn off the secret scanning feature, you can set the secretScanning option to false in publishResource.

const id = await host.publishResource("important data", file, {
  secretScanning: false,
});

Startup script

You can specify a startup script id in the command line using the --startup option. It will run after the server is started.

genaiscript mcp --startup load-resources

Transport Options

The MCP server supports two transport methods:

Stdio Transport (Default)

The default transport uses stdio (standard input/output) for communication. This is the standard way to run MCP servers with most clients.

genaiscript mcp

HTTP Transport

You can also run the MCP server with HTTP transport using the --http flag:

# Basic HTTP server on localhost:8003
genaiscript mcp --http

# Custom port
genaiscript mcp --http --port 3000

# Network accessible (0.0.0.0)
genaiscript mcp --http --network --port 8080

When using HTTP transport, the server will be available at http://host:port/mcp. For example:

http://localhost:8003/mcp (default)
http://0.0.0.0:8080/mcp (network accessible on port 8080)

The HTTP transport uses the Streamable HTTP transport from the MCP specification.

IDE configuration

The mcp command launches the MCP server using the stdio transport.

@modelcontextprotocol/inspector is a MCP client that can be used to inspect the server and list the available tools.

npx --yes @modelcontextprotocol/inspector npx --yes genaiscript mcp

Visual Studio Code Insiders with GitHub Copilot Chat

You will need Visual Studio Code v1.99 or higher and the GitHub Copilot Chat extension installed.

{
  "servers": {
    "genaiscript": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "genaiscript",
        "mcp",
        "--cwd",
        "${workspaceFolder}"
      ],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "genaiscript": {
      "command": "npx",
      "args": ["-y", "genaiscript", "mcp"]
    }
  }
}

Filtering scripts

If you need to filter out which scripts are exposed as MCP tools, you can use the --groups flag and set the mcp group in your scripts.

script({
  group: "mcp",
});

{
  "servers": {
    "genaiscript": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "genaiscript",
        "mcp",
        "--cwd",
        "${workspaceFolder}",
        "--groups",
        "mcp"
      ],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Running scripts from a remote repository

You can use the --remote option to load scripts from a remote repository. GenAIScript will do a shallow clone of the repository and run the script from the clone folder.

npx --yes genaiscript mcp --remote https://github.com/...

There are additional flags to how the repository is cloned:

--remote-branch <branch>: The branch to clone from the remote repository.
--remote-force: Force the clone even if the cloned folder already exists.
--remote-install: Install dependencies after cloning the repository.