Skip to content
Platform Status

Connect

Add tools with TypeScript

For tools with custom business logic, data transformations, or multi-step workflows, the TypeScript functions framework (Gram Functions) creates serverless functions exposed as tools. Unlike OpenAPI-sourced tools, which wrap existing API endpoints, functions run custom code in isolated environments.

Function-sourced tools are ideal for:

  • Custom business logic — calculations, data processing, or decision-making beyond simple API calls, like aggregating data from multiple sources
  • Data transformations — filter, enrich, or summarize data before returning it to the LLM
  • Multi-step workflows — orchestrate several API calls or operations in a single tool

The same steps appear in the dashboard under Connect > Sources > Add Source > Write custom code.

Before you start

Section titled “Before you start”

This guide assumes:

  • An account and project exist (see Getting started)
  • Node.js version 22.18.0 or later is installed

Step 1: Create a project

Section titled “Step 1: Create a project”

Scaffold a new project:

Terminal window
npm create @gram-ai/function@latest

The scaffolder prompts for:

  • Framework — Gram Functions (the simplest path, batteries included) or the official Model Context Protocol SDK for advanced use cases
  • Project name, directory, and git initialization
  • Dependency installation
  • CLI installation — the gram CLI is required to deploy; the scaffolder offers to install it and run gram auth to authenticate

The project contains src/gram.ts (the tools) and src/server.ts (a local MCP server for testing):

Terminal window
└── src
   ├── gram.ts   # Edit me!
   └── server.ts
└── package.json
└── README.md

Step 2: Write tools

Section titled “Step 2: Write tools”

Open src/gram.ts and define tools — as many as needed:

import { Gram } from "@gram-ai/functions";
import * as z from "zod/mini";


const gram = new Gram().tool({
  name: "greet",
  description: "Greet someone special",
  inputSchema: { name: z.string() },
  async execute(ctx, input) {
    return ctx.json({ message: `Hello, ${input.name}!` });
  },
});


export default gram;

For the full framework reference — annotations, tags, environment configuration — see Creating TypeScript tools.

Tools, not servers

These are tools, not a finished MCP server. After deploying, tools can be sliced into multiple MCP servers or combined with tools from other sources.

Test locally before deploying — npm run dev starts the project under MCP Inspector, so tools can be called interactively from the browser.

Step 3: Build and deploy

Section titled “Step 3: Build and deploy”
Terminal window
npm run build
npm run push

Build bundles the functions; push stages the bundle and creates a deployment (under the hood it runs the gram CLI: gram stage function followed by gram push). Once the deployment completes, the functions source and its tools appear under Connect > Sources in the dashboard. Deployment history and retries live under Deployments.

Step 4: Create an MCP server

Section titled “Step 4: Create an MCP server”

Go to Distribute > MCP and click New MCP Server, then add the deployed tools on the server’s Tools tab. The server’s detail page links a hosted installation page with per-client setup instructions. See MCP Servers for visibility, publishing, and team access.

What’s next?

Section titled “What’s next?”