Quickstart

Step 1: Configure your MCP server

To use Elements, you must first setup your MCP Server on the Gram platform. You can find more information about how to do this in our Getting Started guide.

Step 2: Setup your backend

We currently provide a set of handlers from the @gram-ai/elements/server package for Node.js based frameworks like Express, Fastify, and more. The handlers are compatible with the connect-style middleware pattern.

The following example shows how to setup the handlers for Express:

import { createElementsServerHandlers } from '@gram-ai/elements/server'
import express from 'express'
 
const handlers = createElementsServerHandlers()
const app = express()
 
app.use(express.json())
 
app.post('/chat/completions', handlers.chat)

You will need to add an environment variable to your backend and make it available to the process:

GRAM_API_KEY=your-api-key

API Keys can be created from within the Gram dashboard under the Settings tab. The API key must be created with chat scope.

Step 3: Setup your frontend

First ensure that you have installed the required peer dependencies:

pnpm add react react-dom @assistant-ui/react @assistant-ui/react-markdown motion remark-gfm zustand d3

Then install the @gram-ai/elements package:

pnpm add @gram-ai/elements

@gram-ai/elements requires that you wrap your React tree with our context provider and reference our CSS:

import {
  GramElementsProvider,
  Chat,
  type ElementsConfig
} from '@gram-ai/elements'
import '@gram-ai/elements/elements.css'
 
const config: ElementsConfig = {
  projectSlug: '{project_slug}',
  mcp: 'https://app.getgram.ai/mcp/{mcp_slug}',
  // Points to your backend endpoint configured in Step 2
  chatEndpoint: '/chat/completions',
  variant: 'widget',
  welcome: {
    title: 'Hello!',
    subtitle: 'How can I help you today?',
  },
  composer: {
    placeholder: 'Ask me anything...',
  },
  modal: {
    defaultOpen: true,
  },
}
 
export const App = () => {
  return (
    <GramElementsProvider config={config}>
      <Chat />
    </GramElementsProvider>
  )
}

Note: If your application is also using Tailwind, then we recommend that you add the @gram-ai/elements/elements.css import before your own global CSS file so that your CSS is loaded after our CSS.

Step 4: Deploy your application

Be sure to configure your GRAM_API_KEY environment variable in your deployment environment.

Next steps

Complete documentation for the Gram Elements configuration options can be found in the API reference.

Example Next.js application

We have created a simple Next.js application that demonstrates how to use Elements. You can find the code at github.com/speakeasy-api/gram-elements-nextjs-demo .