Speakeasy

https://www.speakeasy.com/docs
Admin
Speakeasy helps teams build great developer experiences by generating type-safe SDKs, Terraform...
Tokens:591,354
Snippets:7,378
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Speakeasy Quickstart Command

Source: https://www.speakeasy.com/docs/speakeasy-reference/cli/quickstart

Use this command to initiate the guided setup for a new SDK. It helps create a new SDK in minutes.

```bash
speakeasy quickstart [flags]
```

--------------------------------

### Clone Example and Install Dependencies

Source: https://www.speakeasy.com/docs/mcp/build/integrate/agents/using-openai-apps-sdk-with-gram-mcp-servers

Clone the example repository and navigate into the 'hello-world-gram' directory. Then, install project dependencies using pnpm.

```bash
git clone https://github.com/speakeasy-api/openai-apps-sdk-examples.git
cd openai-apps-sdk-examples/hello-world-gram
pnpm install
```

--------------------------------

### Start Speakeasy quickstart

Source: https://www.speakeasy.com/docs/speakeasy-reference/cli/mise-toolkit

Initiate the Speakeasy quickstart process to begin using the CLI.

```bash
# Start with quickstart
speakeasy quickstart
```

--------------------------------

### Go SDK Installation

Source: https://www.speakeasy.com/docs/sdk-docs/edit-readme

This snippet shows how to install the Go SDK using the go get command. Ensure the package name matches the one provided in your gen.yaml file.

```bash
go get github.com/client-sdk
```

--------------------------------

### Generate Speakeasy SDK using Quickstart

Source: https://www.speakeasy.com/docs/sdks/languages/typescript/migrating-from-oss

Runs the Speakeasy quickstart command to guide through importing an OpenAPI document and generating an SDK. Select TypeScript as the output language.

```bash
# Run the quickstart command
speakeasy quickstart
```

--------------------------------

### Environment Variables Setup

Source: https://www.speakeasy.com/docs/mcp/build/examples/adding-ai-chat-to-your-app

Example of setting environment variables for API keys and service URLs in a .env file.

```bash
# mcp-agent-service/.env
OPENAI_API_KEY=your_openai_api_key_here
TASKBOARD_SERVER_URL=https://your-ngrok-url.ngrok.io  # Your ngrok URL from Step 1
```

--------------------------------

### Install CLI using Shell Script with Environment Variables

Source: https://www.speakeasy.com/docs/cli-generation/distribute-cli

Example of using environment variables `_INSTALL_DIR` and `_VERSION` with the Linux/macOS install script.

```bash
PETSTORE_INSTALL_DIR=/opt/bin curl -fsSL .../install.sh | bash
PETSTORE_VERSION=v0.2.0 curl -fsSL .../install.sh | bash
```

--------------------------------

### Install Python Package with Extras

Source: https://www.speakeasy.com/docs/speakeasy-reference/generation/python-config

Example of how an end user would install a Python package with specific optional dependencies (extras) using pip.

```bash
pip install my-package[http2]
```

--------------------------------

### Clone and Run TaskBoard Starter App

Source: https://www.speakeasy.com/docs/mcp/build/examples/adding-ai-chat-to-your-app

Clone the TaskBoard repository, checkout the main branch for the CRUD-only version, create an environment file from the example, and start the application using Docker Compose. This sets up the basic task management application before adding chat functionality.

```bash
git clone https://github.com/ritza-co/TaskBoard.git
cd TaskBoard

# Make sure you're on the main branch (CRUD only, no chat)
git checkout main

# Create environment file
cp .env.example .env

# Start with Docker (recommended for testing)
docker-compose up --build
```

--------------------------------

### Install Same Toolset for Multiple Clients

Source: https://www.speakeasy.com/docs/mcp/reference/command-line/install

Demonstrates how to install the same toolset for different client applications.

```bash
# Install the same toolset for multiple clients
gram install claude-code --toolset my-toolset
gram install claude-desktop --toolset my-toolset
gram install cursor --toolset my-toolset
```

--------------------------------

### Setup Skills Command Options

Source: https://www.speakeasy.com/docs/speakeasy-reference/cli/agent/setup-skills

Available options for the `speakeasy agent setup-skills` command, including `--auto` for default skill installation and `-h` for help.

```bash
--auto   Install only default skills (speakeasy-context) without prompting
  -h, --help   help for setup-skills
```

--------------------------------

### Specify Installation URL

Source: https://www.speakeasy.com/docs/speakeasy-reference/cli/run

Provide the language-specific installation URL for SDK installation instructions if the SDK is not published to a package manager.

```bash
speakeasy run --installationURL "https://example.com/install"
```

--------------------------------

### Install openapi CLI with Go

Source: https://www.speakeasy.com/docs/prep-openapi/linting

Install the openapi CLI using the Go programming language's install command.

```bash
go install github.com/speakeasy-api/openapi/cmd/openapi@latest
```

--------------------------------

### Install CLI using Shell Script (Linux/macOS)

Source: https://www.speakeasy.com/docs/cli-generation/distribute-cli

Download and execute the install script for Linux and macOS. Supports overriding installation directory and specifying a version.

```bash
curl -fsSL https://raw.githubusercontent.com/{org}/{repo}/main/scripts/install.sh | bash
```

--------------------------------

### Specify Multiple Installation URLs

Source: https://www.speakeasy.com/docs/speakeasy-reference/cli/run

Provide a map of target IDs to installation URLs for SDK installation instructions when the SDK is not published to a package manager.

```bash
speakeasy run --installationURLs "{\"target1\": \"https://example.com/install1\", \"target2\": \"https://example.com/install2\"}"
```

--------------------------------

### Install for Claude Desktop

Source: https://www.speakeasy.com/docs/mcp/reference/command-line/install

Installs a Gram toolset for Claude Desktop, generating a `.dxt` file in the `Downloads` folder for one-click installation.

```bash
gram install claude-desktop --toolset speakeasy-admin
```

--------------------------------

### Pagination Example

Source: https://www.speakeasy.com/docs/sdks/sdk-docs/edit-readme

Illustrates how to configure pagination for an operation and include it in usage examples.

```APIDOC
## GET /drinks/{page}

### Description
Lists available drinks with offset-limit pagination, selectable for 'usage' and 'pagination' sections.

### Method
GET

### Endpoint
/drinks/{page}

### Parameters
#### Path Parameters
- **page** (string) - Required - The page number for pagination.

### Request Body

### Request Example
```yaml
/drinks/{page}:
  get:
    operationId: listDrinks
    x-speakeasy-pagination:
      type: offsetLimit
      inputs:
        - name: page
          in: parameters
          type: page
    x-speakeasy-usage-example:
      title: "Browse available drinks"
      position: 2
      tags:
        - usage
        - pagination
```

### Response

#### Success Response (200)

#### Response Example

```

--------------------------------

### Install for Claude Desktop with Custom Output Directory

Source: https://www.speakeasy.com/docs/mcp/reference/command-line/install

Installs a Gram toolset for Claude Desktop, specifying a custom output directory for the generated `.dxt` installation file.

```bash
gram install claude-desktop --toolset speakeasy-admin --output-dir ~/Desktop
```

--------------------------------

### Install CLI using PowerShell (Windows)

Source: https://www.speakeasy.com/docs/cli-generation/distribute-cli

Download and execute the install script for Windows using PowerShell. Supports overriding installation directory and specifying a version.

```powershell
iwr -useb https://raw.githubusercontent.com/{org}/{repo}/main/scripts/install.ps1 | iex
```

--------------------------------

### Create Gram Functions Project

Source: https://www.speakeasy.com/docs/mcp/build/examples/consuming-external-apis

Use this command to initialize a new Gram Functions project. Refer to the Getting Started guide for detailed instructions.

```bash
npm create gram-functions@latest
```

--------------------------------

### Globally Override Method Names

Source: https://www.speakeasy.com/docs/customize/methods

Use the `x-speakeasy-name-override` extension at the root of your OpenAPI schema to override method names globally based on `operationId` regex matching. This example overrides methods starting with 'get' to 'get' and 'post' to 'create'.

```yaml
openapi: 3.1.0
info:
  title: Test
  version: 0.0.1
servers:
  - url: https://httpbin.org
security:
  - basicAuth: []
x-speakeasy-name-override:
  - operationId: ^get.*
    methodNameOverride: get
  - operationId: ^post.*
    methodNameOverride: create
paths:
  /test:
    get:
      operationId: getTest
      responses:
        "200":
          description: OK
    post:
      operationId: postTest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Test"
      responses:
        "200":
        description: OK

```

--------------------------------

### Create SDK with Speakeasy CLI Quickstart

Source: https://www.speakeasy.com/docs/sdk-design/php/oss-comparison-php

Initiate the SDK creation process with Speakeasy CLI using the quickstart command. This command sets up a new SDK project.

```bash
docker run --rm -v "./app:/app" seimage speakeasy quickstart
```

--------------------------------

### Get Pet By ID - TypeScript SDK

Source: https://www.speakeasy.com/docs/sdks/sdk-docs/code-samples/code-samples-api

Example of using the Speakeasy SDK to retrieve a pet by its ID. Ensure the API key is set in the environment variables or passed directly. Installation instructions are not yet supported for this endpoint.

```typescript
import { Petstore } from "petstore";

const petstore = new Petstore({
  serverURL: "https://api.example.com",
  apiKey: process.env["PETSTORE_API_KEY"] ?? "",
});

async function run() {
  const result = await petstore.pet.getPetById({
    petId: 311674,
  });

  // Handle the result
  console.log(result);
}

run();
```

--------------------------------

### Quickstart Command Options

Source: https://www.speakeasy.com/docs/speakeasy-reference/cli/quickstart

Configure the quickstart command using various flags to specify the template, SDK name, output directory, and more.

```bash
  -f, --from string           template to use for the quickstart command.
                              Create a new sandbox at https://app.speakeasy.com/sandbox
  -h, --help                  help for quickstart
      --init-git              initialize a git repository in the output directory
  -n, --name string           SDK name in PascalCase (e.g., "MyCompanySDK"). Users access SDK methods with myCompanySDK.DoThing()
  -o, --out-dir string        output directory for the quickstart command
      --output string         how to display output (available options: [summary, console, mermaid]) (default "summary")
  -p, --package-name string   package name for the generated SDK (e.g., "my-company-sdk" for npm, Go module path for Go)
  -s, --schema string         local filepath, URL, or registry reference for the OpenAPI schema (e.g., ./spec.yaml, https://..., namespace, org/workspace/namespace@tag)
      --skip-compile          skip compilation during generation after setup
      --skip-interactive      skip all interactive prompts and use defaults (useful for non-interactive environments like CI)
  -t, --target string         generation target (available options: [cli, csharp, go, java, mcp-typescript, php, postman, python, ruby, terraform, typescript])
```

--------------------------------

### Run Speakeasy Quickstart

Source: https://www.speakeasy.com/docs/create-client-sdks

Initiate the Speakeasy SDK generation process for the first time.

```bash
speakeasy quickstart
```

--------------------------------

### Generate Taskmaster MCP Installation Package

Source: https://www.speakeasy.com/docs/mcp/build/integrate/clients/using-claude-desktop-with-gram-mcp-server

Example of generating an installation package for the Taskmaster toolset.

```bash
gram install claude-desktop --toolset taskmaster
```

--------------------------------

### Go Import Example (Global)

Source: https://www.speakeasy.com/docs/sdks/customize/structure/imports

Demonstrates how to import the SDK when global imports are configured for Go.

```go
import (
  "github.com/speakeasy/bar"
)
```

--------------------------------

### Start Gemini CLI

Source: https://www.speakeasy.com/docs/mcp/build/integrate/clients/using-gemini-cli-with-gram-mcp-servers

Starts the Gemini CLI application. This command is used to interact with the CLI after setup.

```bash
gemini
```

--------------------------------

### Generate Go SDK with Speakeasy CLI

Source: https://www.speakeasy.com/docs/sdk-design/golang/oss-comparison-go

Use the Speakeasy CLI's quickstart command to generate a Go SDK. This command automates the process and provides feedback through logs.

```bash
# Generate Petstore SDK using Speakeasy go generator
speakeasy quickstart
```

--------------------------------

### Initialize New SDK Repository with Speakeasy

Source: https://www.speakeasy.com/docs/sdks/manage/migrate/workflow-migration

Commands to set up a new SDK repository using Speakeasy's quickstart and GitHub integration. After running these, copy the `gen.yaml` from an old SDK to `.speakeasy/gen.yaml` in the new repository.

```bash
speakeasy quickstart
speakeasy configure github
```

--------------------------------

### Provide Example Value with x-speakeasy-example

Source: https://www.speakeasy.com/docs/sdks/prep-openapi/best-practices

Use `x-speakeasy-example` to provide an example value for the `Authentication` section of the SDK `README.md`, indicating how users should instantiate the SDK with their security token.

```yaml
      x-speakeasy-example: "<YOUR_API_KEY>"
```

--------------------------------

### GitHub Actions workflow to install and use Speakeasy CLI

Source: https://www.speakeasy.com/docs/speakeasy-reference/cli/mise-toolkit

Example GitHub Actions workflow demonstrating how to install mise and the Speakeasy CLI, and then use the CLI within a workflow. Ensure your SPEAKEASY_API_KEY is set as a secret.

```yaml
# Example GitHub Actions workflow
- name: Install mise
  uses: jdx/mise-action@v2
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

- name: Install Speakeasy CLI
  run: mise use aqua:speakeasy-api/speakeasy

- name: Use Speakeasy CLI
  run: speakeasy quickstart
  env:
    SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}
```

--------------------------------

### Prepare Directory for ogen SDK

Source: https://www.speakeasy.com/docs/sdk-design/golang/oss-comparison-go

Set up a new directory for generating an SDK with ogen and initialize a Go module within it.

```bash
mkdir petstore-sdk-go-ogen && cd petstore-sdk-go-ogen
```

```bash
go mod init petstore-sdk-go-ogen
```

--------------------------------

### Run Speakeasy Quickstart for MCP Server

Source: https://www.speakeasy.com/docs/standalone-mcp/build-server

Initiate the Speakeasy quickstart process with the --mcp flag to generate an MCP server project.

```bash
speakeasy quickstart --mcp
```

--------------------------------

### Dependency Version Mismatch Error Example

Source: https://www.speakeasy.com/docs/sdks/manage/migrate/poetry-2-update

This error message indicates that the installed Poetry version is older than the required 2.0.0.

```text
WARN	can't compile - Dependency Version Mismatch - Install Poetry by following the instructions at https://python-poetry.org/docs/#installing-with-pipx.
ERROR	dependency version not met -- poetry - version 1.8.5 is less than required version 2.0.0
FATAL	Failed to generate SDK to XXX
```

--------------------------------

### Set Up Contract Testing Command

Source: https://www.speakeasy.com/docs/speakeasy-reference/skills

Example command to set up contract testing for a generated SDK.

```bash
Set up contract testing for my generated SDK
```

--------------------------------

### Get Speakeasy SDK TypeScript Version

Source: https://www.speakeasy.com/docs/speakeasy-reference/cli/bump

Retrieves the current version of the Speakeasy SDK for TypeScript. Ensure the SDK is installed.

```javascript
const version = require("@speakeasy/sdk-typescript").version;
console.log(version);
```

--------------------------------

### Hono Backend Setup

Source: https://www.speakeasy.com/docs/mcp/gram-elements/quickstart

Set up a backend endpoint for Gram Elements using Hono. This example demonstrates basic integration.

```typescript
import { createHonoHandler } from '@gram-ai/elements/server/hono'
import { Hono } from 'hono'

const app = new Hono()

app.post('/chat/session', createHonoHandler({
  embedOrigin: 'http://localhost:3000',
  userIdentifier: 'user-123',
  expiresAfter: 3600,
}))

export default app
```

--------------------------------

### Quick Install with Automatic Configuration

Source: https://www.speakeasy.com/docs/mcp/reference/command-line/install

Use this command for a straightforward installation where the CLI automatically fetches necessary metadata and configures the native HTTP transport.

```bash
# Install for Claude Code using automatic configuration
gram install claude-code --toolset my-toolset

# The CLI will:
# 1. Fetch toolset metadata from Gram API
# 2. Derive MCP URL, headers, and env vars automatically
# 3. Create .mcp.json with native HTTP transport
```

--------------------------------

### Usage Examples

Source: https://www.speakeasy.com/docs/sdks/customize/runtime/base64-json-inputs

Demonstrates how to use the SDK method with different input types: a filesystem path, an open binary stream, and a pre-encoded base64 string.

```APIDOC
## Usage

```python
# filesystem path
sdk.post_base64_input_mode(
    data_byte=Path("./payload.bin"),
    data_content_encoding="dGVzdA==",
)

# open binary stream
with open("./payload.bin", "rb") as fh:
    sdk.post_base64_input_mode(data_byte=fh, data_content_encoding=fh)

# pre-encoded base64 string
sdk.post_base64_input_mode(data_byte="dGVzdA==", data_content_encoding="dGVzdA==")
```
```

--------------------------------

### TypeScript Compile Script Example

Source: https://www.speakeasy.com/docs/sdks/guides/override-compile

A bash script to install npm dependencies and build the TypeScript SDK. Ensure this script is executable.

```bash
#!/usr/bin/env bash

set -e

npm install
npm run build
```

--------------------------------

### Generate CLI with Speakeasy Quickstart

Source: https://www.speakeasy.com/docs/cli-generation/create-cli

Run the Speakeasy quickstart command and select the CLI target to begin generating a CLI. The interactive flow prompts for package name, CLI name, and environment variable prefix.

```bash
speakeasy quickstart --target cli
```

--------------------------------

### Speakeasy Tag Command Usage

Source: https://www.speakeasy.com/docs/speakeasy-reference/cli/tag

This shows the basic usage of the speakeasy tag command. No specific setup is required beyond having the Speakeasy CLI installed.

```bash
speakeasy tag [flags]
```

--------------------------------

### Initialize and Use SDK to List Pets

Source: https://www.speakeasy.com/docs/customize-sdks/sdk-docs

This Go code snippet shows how to initialize the SDK with API key authentication and then call the ListPets operation. Ensure you replace 'YOUR_API_KEY' with your actual API key.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/client-sdk"
    "github.com/client-sdk/pkg/models/shared"
    "github.com/client-sdk/pkg/models/operations"
)

func main() {
    ctx := context.Background()

    opts := []sdk.SDKOption{
        sdk.WithSecurity(shared.Security{
            APIKey: shared.SchemeAPIKey{
                APIKey: "YOUR_API_KEY",
            },
        }),
    }

    s := sdk.New(opts...)

    res, err := s.ListPets(ctx)
    if err != nil {
        log.Fatal(err)
    }

    if res.Pets != nil {
        // handle response
    }
}
```

--------------------------------

### Next.js App Router Backend Setup

Source: https://www.speakeasy.com/docs/mcp/gram-elements/quickstart

Set up a backend endpoint for Gram Elements using Next.js App Router. This example shows static configuration.

```typescript
// app/chat/session/route.ts
import { createNextHandler } from '@gram-ai/elements/server/nextjs'

export const POST = createNextHandler({
  embedOrigin: 'http://localhost:3000',
  userIdentifier: 'user-123',
  expiresAfter: 3600,
})
```

--------------------------------

### Inherited Options for Quickstart

Source: https://www.speakeasy.com/docs/speakeasy-reference/cli/quickstart

These options are inherited from parent commands and can be used with the quickstart command.

```bash
      --logLevel string   the log level (available options: [info, warn, error]) (default "info")
```

--------------------------------

### Get Vintage Method in Multiple Namespaces

Source: https://www.speakeasy.com/docs/customize-sdks/namespaces

This example demonstrates how the `getVintage` operation, tagged with both 'drinks' and 'wine', can be accessed through either the `Drinks` or `Wine` namespace in the generated SDK.

```APIDOC
## GET /drink/{drink_type}/get_vintage/

### Description
Check the vintage of the wine.

### Method
GET

### Endpoint
/drink/{drink_type}/get_vintage/

### Parameters
#### Path Parameters
- **drink_type** (string) - Required - The type of drink

### Responses
#### Success Response (200)
- **vintage** (Vintage) - The wine vintage

### Request Example
```json
{
  "example": ""
}
```

### Response Example
```json
{
  "example": "{\"vintage\": \"1999\"}"
}
```

## SDK Usage Examples
```typescript
// Get the Vintage
sdk.Drinks.GetVintage("wine")
sdk.Wine.GetVintage("wine")
```
```

--------------------------------

### Go Usage Example for AddPet (OpenAPI)

Source: https://www.speakeasy.com/docs/sdks/languages/golang/oss-comparison-go

This Go code snippet demonstrates how to use the AddPet endpoint as generated by OpenAPI. It includes basic setup and error handling.

```go
package main

import (
    "context"
    "fmt"
    "os"
    openapiclient "github.com/GIT_USER_ID/GIT_REPO_ID"
)

func main() {
    pet := *openapiclient.NewPet("doggie", []string{"PhotoUrls_example"}) // Pet | Create a new pet in the store

    configuration := openapiclient.NewConfiguration()
    apiClient := openapiclient.NewAPIClient(configuration)
    resp, r, err := apiClient.PetApi.AddPet(context.Background()).Pet(pet).Execute()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `PetApi.AddPet``: %v\n", err)
        fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    }
    // response from `AddPet`: Pet
    fmt.Fprintf(os.Stdout, "Response from `PetApi.AddPet`: %v\n", resp)
}
```

--------------------------------

### Configure pnpm Compile Command in gen.yaml

Source: https://www.speakeasy.com/docs/sdks/guides/pnpm-default

In your `gen.yaml` file, specify the `compileCommand` for TypeScript to use pnpm for installation. This is crucial for monorepo setups where pnpm manages dependencies.

```yaml
typescript:
  compileCommand:
    - pnpm
    - install
```

--------------------------------

### Install with API Key

Source: https://www.speakeasy.com/docs/mcp/reference/command-line/install

Installs a toolset and provides an API key for authentication. Falls back to environment variables or profile if not provided.

```bash
gram install claude-code --toolset speakeasy-admin --api-key sk_1234567890
```

--------------------------------

### Go Import Example (Non-Global)

Source: https://www.speakeasy.com/docs/sdks/customize/structure/imports

Shows the alternative way to import when global imports are not configured for Go.

```go
import (
  "github.com/speakeasy/bar"
  "github.com/speakeasy/bar/models/operations"
  "github.com/speakeasy/bar/models/components"
)
```

--------------------------------

### Speakeasy Dockerfile Setup

Source: https://www.speakeasy.com/docs/sdk-design/php/oss-comparison-php

This Dockerfile sets up an Alpine Linux environment with necessary tools and installs the Speakeasy CLI. Replace 'YourApiKey' with your actual Speakeasy API key.

```dockerfile
FROM alpine:3.19
WORKDIR /app
RUN apk add bash go curl unzip sudo nodejs npm
RUN curl -fsSL https://go.speakeasy.com/cli-install.sh | sh;
ENV GOPATH=/root/go
ENV PATH=$PATH:$GOPATH/bin
ENV SPEAKEASY_API_KEY=YourApiKey
```

--------------------------------

### Pipe output to another command

Source: https://www.speakeasy.com/docs/speakeasy-reference/cli/openapi/snip

The command's output can be piped to other commands for further processing. This example removes the GET operation on `/debug` and pipes the result to `speakeasy openapi lint`.

```bash
speakeasy openapi snip --schema ./spec.yaml --operation /debug:GET | speakeasy openapi lint
```

--------------------------------

### Instantiate SDK with Global API Key (PHP)

Source: https://www.speakeasy.com/docs/sdks/customize/authentication/configuration

Set up the SDK with your API key using the builder. The provided key will be used for all subsequent API calls.

```php
declare(strict_types=1);

  require 'vendor/autoload.php';

  use OpenAPI\OpenAPI;

  $sdk = OpenAPI\SDK::builder()
      ->setSecurity(
          new OpenAPI\Security(
              apiKey: "<YOUR_API_KEY_HERE>"
          )
      )
      ->build();

  try {
      $response = $sdk->drinks->listDrinks();

      if ($response->drinks !== null) {
          // handle response
      }
  } catch (Exception $e) {
      // handle exception
  }
```

--------------------------------

### Basic `gram install` Usage

Source: https://www.speakeasy.com/docs/mcp/reference/command-line/install

Use this command to automatically fetch toolset configuration from the Gram API and set up the appropriate MCP server. The CLI derives the MCP URL, authentication headers, and environment variables, then creates the necessary configuration file.

```bash
gram install claude-code --toolset <your-toolset-slug>
```

--------------------------------

### Initialize Speakeasy SDK with Client Credentials (Ruby)

Source: https://www.speakeasy.com/docs/sdks/customize/authentication/oauth

Initialize the Speakeasy SDK in Ruby using client ID and client secret. This example shows the basic setup for authentication with the SDK.

```ruby
require 'speakeasy'

  s = ::Speakeasy::SDK.new(
    security: ::Speakeasy::Models::Components::Security.new(
      client_id: '<YOUR_CLIENT_ID_HERE>',
      client_secret: '<YOUR_CLIENT_ID_HERE>',
    ),
  )

  res = s.drinks.list_drinks

  if !res.drinks.nil?
    # handle response
  end
```

--------------------------------

### Python Import Example (Global)

Source: https://www.speakeasy.com/docs/sdks/customize/structure/imports

Shows how to import the SDK when global imports are configured for Python.

```python
import speakeasybar
```

--------------------------------

### Initialize Speakeasy SDK with Client Credentials (C#)

Source: https://www.speakeasy.com/docs/sdks/customize/authentication/oauth

Initialize the Speakeasy SDK in C# using client ID and client secret. This example shows the asynchronous setup for security credentials.

```csharp
using Speakeasy;
  using Speakeasy.Models.Components;

  var sdk = new SDK(
      security: new Security()
      {
          ClientID = "<YOUR_CLIENT_ID_HERE>",
          ClientSecret = "<YOUR_CLIENT_ID_HERE>"
      }
  );

  try
  {
      var res = await sdk.Drinks.ListDrinksAsync();

      if (res.Drinks != null)
      {
          // handle response
      }
  }
  catch (Exception ex)
  {
    // handle exception
  }
```

--------------------------------

### MCP Client Configuration for Pass-through Authentication

Source: https://www.speakeasy.com/docs/mcp/secure/public-private-servers

Example of an MCP client configuration using pass-through authentication. This setup is used when users provide their own API keys to access the underlying services.

```json
{
  "mcpServers": {
    "GramAcmetodo": {
      "command": "npx",
      "args": [
          "mcp-remote",
          "https://app.getgram.ai/mcp/ritza-rzx-todo",
          "--header",
          "MCP-TODO-API-API-KEY:sk-acmetodo-THISISSECRET"
        ]
    }
  }
}
```

--------------------------------

### Download Ogen Example Spec

Source: https://www.speakeasy.com/docs/sdks/languages/golang/oss-comparison-go

Replace the existing `petstore.yaml` with a simplified version from the ogen documentation to resolve generation issues.

```bash
curl https://raw.githubusercontent.com/ogen-go/web/main/examples/petstore.yml --output petstore.yaml
```

--------------------------------

### Initialize Python Project with uv

Source: https://www.speakeasy.com/docs/mcp/build/integrate/agents/using-vellum-workflows-sdk-with-gram-mcp-servers

Use these commands to create a project directory and initialize a Python project using the `uv` package manager.

```bash
mkdir vellum-workflows-sdk
cd vellum-workflows-sdk

uv init
```

--------------------------------

### Override Operation Names with x-speakeasy-name-override

Source: https://www.speakeasy.com/docs/sdks/prep-openapi/best-practices

Use `x-speakeasy-name-override` to simplify generated SDK method names by overriding `operationId` values. This example uses a regex to match and rename operations starting with `list_` to `list`.

```yaml
x-speakeasy-name-override:
  - operationId: ^list_.*
    methodNameOverride: list
      operationId: list_drinks_v2_get
```

--------------------------------

### Example Go SDK Structure with Custom Class Name

Source: https://www.speakeasy.com/docs/customize-sdks/sdk-docs

Illustrates the resulting Go package structure when a custom SDK class name is configured.

```go
package petshop

import (
	"net/http"

	"openapi/pkg/utils"
)

var ServerList = []string{
	"http://petstore.speakeasy.io/v1",
}

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

type PetShop struct {

Pets *Pets

	_defaultClient  HTTPClient
	_securityClient HTTPClient

	_serverURL  string
	_language   string
	_sdkVersion string
	_genVersion string
}
```

--------------------------------

### Example Hook Implementation in Go

Source: https://www.speakeasy.com/docs/sdks/customize/code/sdk-hooks

A basic Go hook implementation that satisfies the interfaces for SDK initialization, before request, after success, and after error lifecycle events. This serves as a starting point for custom hook logic.

```go
package hooks

  import (
    "net/http"
  )

  type ExampleHook struct{}

  var (
    _ sdkInitHook       = (*ExampleHook)(nil)
    _ beforeRequestHook = (*ExampleHook)(nil)
    _ afterSuccessHook  = (*ExampleHook)(nil)
    _ afterErrorHook    = (*ExampleHook)(nil)
  )

```

--------------------------------

### Get Project Metrics Summary cURL Example

Source: https://www.speakeasy.com/docs/mcp/observe/insights/api-reference

This cURL command demonstrates how to call the getProjectMetricsSummary endpoint. It includes necessary headers for authentication and content type, and a JSON payload with date range filters.

```bash
curl -X POST "https://app.getgram.ai/rpc/telemetry.getProjectMetricsSummary" \
  -H "Content-Type: application/json" \
  -H "Gram-Key: <your-api-key>" \
  -H "Gram-Project: <your-project-slug>" \
  -d '{
    "from": "2025-12-01T00:00:00Z",
    "to": "2025-12-31T23:59:59Z"
  }'
```

--------------------------------

### Authenticated Connection to Gram MCP Server

Source: https://www.speakeasy.com/docs/mcp/build/integrate/agents/using-openai-agents-sdk-with-gram-mcp-servers

Example for establishing an authenticated connection to Gram MCP servers. This requires including specific authentication headers in the HostedMCPTool configuration, which may vary based on your MCP server setup.

```python
import os
from agents import Agent, Runner, HostedMCPTool
```

--------------------------------

### Use Instructions with MCP Tools in Pydantic AI

Source: https://www.speakeasy.com/docs/mcp/build/integrate/agents/using-pydantic-ai-with-gram-mcp-servers

Control agent behavior by providing specific instructions when using MCP tools. This example sets a persona and guides the agent's decision-making process for deployment recommendations.

```python
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP
from pydantic_ai.models.openai import OpenAIModel

# Create MCP server connection
mcp_server = MCPServerStreamableHTTP(
    url="https://app.getgram.ai/mcp/canipushtoprod"
)

agent = Agent(
    OpenAIModel("gpt-4-turbo"),
    instructions=(
        "You are a deployment advisor. Always be cautious and "
        "consider the day of the week and current vibe when "
        "making deployment recommendations."
    ),
    toolsets=[mcp_server]
)

async with agent:
    result = await agent.run("Should we deploy the new feature?")
    print(result.output)

```
Tokens:
Raw