diff --git a/docs/gram/clients/using-zapier-with-gram-mcp-server.mdx b/docs/gram/clients/using-zapier-with-gram-mcp-server.mdx new file mode 100644 index 00000000..d698af2c --- /dev/null +++ b/docs/gram/clients/using-zapier-with-gram-mcp-server.mdx @@ -0,0 +1,196 @@ +# Using Zapier with Gram-hosted MCP servers + +[Zapier](https://zapier.com/) is a leading automation platform that connects thousands of apps. With the **MCP Client by Zapier** integration, you can connect Zapier to your [Gram-hosted MCP servers](/blog/release-gram-beta), allowing you to trigger tools and actions on your MCP server directly from your Zapier workflows. + +This guide shows you how to connect Zapier to a Gram-hosted MCP server using an example Push Advisor API. You'll learn how to set up the connection, create a Zap that you can interact with in a Slack channel and that uses custom MCP tools to check whether today is a good day to push to production. + +## Prerequisites + +To follow this tutorial, you need: + +- Admin access to a [Slack](https://slack.com/) workspace +- A [Gram account](/product/gram) +- A [Zapier account](https://zapier.com/) (7-day free trial available) + +## Creating a Gram MCP server + +If you already have a Gram MCP server configured (like the Push Advisor from other guides), you can skip to [connecting Zapier to your Gram-hosted MCP server](#creating-a-zap-with-gram-mcp). + +### Setting up a Gram project + +In the [Gram dashboard](https://app.getgram.ai), click **New Project** to create a new project. Enter a project name and click **Submit**. + +![get-started](/assets/docs/gram/img/guides/zapier/get-started.png) + +Once you've created the project, click the **Get Started** button. + +Choose **Start from API**. Gram then guides you through the following steps. + +### Step 1: Upload the OpenAPI document + +Upload the [Push Advisor OpenAPI document](https://github.com/ritza-co/gram-examples/blob/main/push-advisor-api/openapi.yaml), enter `Push Advisor` as the API name, and click **Continue**. + +![open-api-doc](/assets/docs/gram/img/guides/zapier/upload-openAPI.png) + +### Step 2: Create a toolset + +Give your toolset a name (for example, `push_advisor`) and click **Continue**. + +![name-toolset](/assets/docs/gram/img/guides/zapier/name-toolset.png) + +Notice that the **Name Your Toolset** dialog displays the names of the tools that Gram will generate from your OpenAPI document. + +### Step 3: Configure MCP + +Enter a URL slug for the MCP server (for example, `zapier-push-advisor`) and click **Continue**. + +![mcp-slug](/assets/docs/gram/img/guides/zapier/mcp-slug.png) + +This finalizes the creation of the toolset from the OpenAPI document. + +### Step 4: Test the toolset + +We can test that our tools work correctly using the **Gram Playground**. Navigate to the **Playground** page. The chatbot page lists all our available tools on the left. + +Ask some questions in the chat that would trigger tool calls. For example: + +``` +Can I push to prod? +``` + +The AI determines the correct tool to call and returns a response based on the answer data. + +![playground](/assets/docs/gram/img/guides/zapier/playground.gif) + +### Creating an API key + +Navigate to **Settings** and click **New API Key**. Name your key and click **Create**. Then copy the key and store it somewhere secure (we'll use it later to integrate with Zapier). + +![gram-api-key](/assets/docs/gram/img/guides/zapier/gram-api-key.png) + +### Publishing an MCP server + +Go to the **MCP** tab and click on your toolset. Click **Enable**, then scroll down and change the visibility to **Public**. + +![public-visibility](/assets/docs/gram/img/guides/zapier/public-visibility.png) + +Finally, copy the **Hosted URL** from the configuration (for example, `https://app.getgram.ai/mcp/your-mcp-slug`). We'll use the URL along with our API key to integrate with Zapier. + +## Creating a Zap with Gram MCP + +Let's create a Zap that interacts with our user through Slack and makes use of our MCP toolset. + +To get started, sign in to your Zapier account, click **+ Create**, and choose **Zaps**. + +![zapier-create](/assets/docs/gram/img/guides/zapier/zapier-create.png) + +### Step 1: Create the Trigger + +Click the placeholder for the trigger to open the trigger configuration screen and select **Slack** from the options list. + +For the **Trigger event** select **New Message Posted to Channel**, then sign in to your Slack account under **Account** and press **Continue**. + +![trigger-config-1](/assets/docs/gram/img/guides/zapier/trigger-config-1.png) + +Next, in the **Configure** tab, select your preferred **Channel** from your Slack workspace and click **Continue**. + +![trigger-config-2](/assets/docs/gram/img/guides/zapier/trigger-config-2.png) + +Before testing the trigger, open your chosen Slack channel and send a message that we can use for the remaining setup (for example, *"Should I push?"*). Then test the trigger, select that message from the recent records list, and click **Continue with selected record**. + +![trigger-config-3](/assets/docs/gram/img/guides/zapier/trigger-config-3.png) + +### Step 2: Add the MCP Client action + +From the Actions menu, search for `MCP` and choose **MCP Client**. + +Select **Run Tool** as the **Action event**. + +![mcp-client](/assets/docs/gram/img/guides/zapier/mcp-client.png) + +Click **Sign in** under **Account** and enter your Gram **Server URL** and **Bearer Token** (this is the API key you copied from Gram earlier). Set **Transport** to **Streamable HTTP** and set **OAuth** to **No**, then click **Yes, Continue to MCP Client**. + +![zapier-gram-account](/assets/docs/gram/img/guides/zapier/zapier-gram-account.png) + +Click **Continue**. In the **Configure** section, click the **Tool** dropdown to load the list of tools from your Gram server. Select the `can_i_push_to_prod` tool. + +![select-tool](/assets/docs/gram/img/guides/zapier/select-tool.png) + +Click **Continue** and then **Test step**. You should see a successful response from the Gram MCP server containing the tool result. + +![tool-result](/assets/docs/gram/img/guides/zapier/tool-result.png) + +Once you're confident that you've connected the Gram server, click the **+** button to add another action. + +### Step 3: AI response + +To demonstrate how we can integrate an LLM into our workflow using Zapier, we will add an **AI by Zapier** action. We will pass it the result of our MCP tool call and get a customized response. + +When we add the action, we are presented with a prompt builder screen. Here we can customize our AI Model to do exactly what we want. + +Select **Custom prompt** for **Build mode** and select your preferred **Model**. Under **Input fields**, press **+ Add field**. Give the field a name, then under **Field value**, press the **+** sign, and find the **Structured Content Reason** field returned from the MCP tool. Finally, set the **Content Type** to **Text** and press **Save**. + +![input-ai-field](/assets/docs/gram/img/guides/zapier/input-ai-field.png) + +In the **Prompt** field, instruct the bot to provide a friendly response to questions about pushing to production, making sure to use the result of the tool. A stronger prompt will cause the AI to behave more predictably. + +For example, this is a reasonably strong prompt: + +``` +You are a helpful and friendly DevOps assistant for a software engineering team. A user has just asked if it is safe to push to production. + +You will be provided with the raw output from the "Push Advisor" tool (should_i_push), which checks if we are allowed to push to production. + +Your task is to write a concise Slack reply based on this status: +1. If the status is POSITIVE (e.g., "yes", "go for it", "safe", "chill"): + - Give them the green light. + - Be encouraging and enthusiastic e.g., "All systems go! 🚀" or similar. + +2. If the status is NEGATIVE (e.g., "no", "hold", "unsafe", "bad vibes"): + - Warn them strictly not to push. + - Be polite but firm (e.g., "Hold your horses! 🛑 The vibes are off."). + +3. If the status is unclear: + - Advise caution. + +**Rules:** +- Keep the message short (under 2 sentences). +- Do not mention "JSON" or internal data structures. +- Use an appropriate emoji. +- Address the team directly. +``` + +Zapier will give you an estimation of your prompt's strength and allow you to generate a sample preview response, so you can see whether you're satisfied with its behavior. Once you're happy with the prompt, click **Finish**. + +![prompt-config](/assets/docs/gram/img/guides/zapier/prompt-config.png) + +### Step 4: Reply in Slack + +Add a final action step and select **Slack**. Choose **Send Channel Message** as the **Action event** and click **Continue**. + +![slack-send](/assets/docs/gram/img/guides/zapier/slack-send.png) + +In the **Channel** field, select the same channel as the trigger. In the **Message Text** field, insert the output from the **AI by Zapier** step. Make sure **Send as a bot?** is set to **Yes**. This ensures that the bot message doesn't kick off the trigger action, causing a loop. + +![slack-message-config](/assets/docs/gram/img/guides/zapier/slack-message-config.png) + +Click **Continue** and test the step to send a message to Slack. + +### Step 5: Deploy and test your Zap + +To deploy and enable your Zap, first rename it something relevant, then click **Publish**. + +![rename-and-deploy](/assets/docs/gram/img/guides/zapier/rename-and-deploy.png) + +Your Zap is now live, and you can test it by sending a message in your Slack channel. + +![slack-message](/assets/docs/gram/img/guides/zapier/slack-message.png) + +## What's next + +You have successfully connected Zapier to a Gram-hosted MCP server. This allows you to bring any API or tool hosted on Gram into your Zapier automation workflows. + +When you add more tools to your Gram toolset, they become available in the **Run Tool** dropdown in Zapier. + +Ready to build your own MCP server? [Try Gram today](/product/gram) and see how easy it is to turn any API into agent-ready tools. + diff --git a/public/assets/docs/gram/img/guides/zapier/get-started.png b/public/assets/docs/gram/img/guides/zapier/get-started.png new file mode 100644 index 00000000..56be3fc9 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/get-started.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/gram-api-key.png b/public/assets/docs/gram/img/guides/zapier/gram-api-key.png new file mode 100644 index 00000000..1b5581c3 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/gram-api-key.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/input-ai-field.png b/public/assets/docs/gram/img/guides/zapier/input-ai-field.png new file mode 100644 index 00000000..52a679cb Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/input-ai-field.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/mcp-client.png b/public/assets/docs/gram/img/guides/zapier/mcp-client.png new file mode 100644 index 00000000..0f0d2bdb Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/mcp-client.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/mcp-slug.png b/public/assets/docs/gram/img/guides/zapier/mcp-slug.png new file mode 100644 index 00000000..d1ec2566 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/mcp-slug.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/name-toolset.png b/public/assets/docs/gram/img/guides/zapier/name-toolset.png new file mode 100644 index 00000000..c2f4edee Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/name-toolset.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/playground.gif b/public/assets/docs/gram/img/guides/zapier/playground.gif new file mode 100644 index 00000000..fd06ca3b Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/playground.gif differ diff --git a/public/assets/docs/gram/img/guides/zapier/prompt-config.png b/public/assets/docs/gram/img/guides/zapier/prompt-config.png new file mode 100644 index 00000000..338efdb4 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/prompt-config.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/public-visibility.png b/public/assets/docs/gram/img/guides/zapier/public-visibility.png new file mode 100644 index 00000000..bc8bd878 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/public-visibility.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/rename-and-deploy.png b/public/assets/docs/gram/img/guides/zapier/rename-and-deploy.png new file mode 100644 index 00000000..6bf073d9 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/rename-and-deploy.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/select-tool.png b/public/assets/docs/gram/img/guides/zapier/select-tool.png new file mode 100644 index 00000000..bc008b3e Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/select-tool.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/slack-message-config.png b/public/assets/docs/gram/img/guides/zapier/slack-message-config.png new file mode 100644 index 00000000..24b4de7c Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/slack-message-config.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/slack-message.png b/public/assets/docs/gram/img/guides/zapier/slack-message.png new file mode 100644 index 00000000..0fad432d Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/slack-message.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/slack-send.png b/public/assets/docs/gram/img/guides/zapier/slack-send.png new file mode 100644 index 00000000..a3c33d23 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/slack-send.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/tool-result.png b/public/assets/docs/gram/img/guides/zapier/tool-result.png new file mode 100644 index 00000000..4dea6374 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/tool-result.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/trigger-config-1.png b/public/assets/docs/gram/img/guides/zapier/trigger-config-1.png new file mode 100644 index 00000000..774dd2fe Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/trigger-config-1.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/trigger-config-2.png b/public/assets/docs/gram/img/guides/zapier/trigger-config-2.png new file mode 100644 index 00000000..f76cab67 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/trigger-config-2.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/trigger-config-3.png b/public/assets/docs/gram/img/guides/zapier/trigger-config-3.png new file mode 100644 index 00000000..75958951 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/trigger-config-3.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/upload-openAPI.png b/public/assets/docs/gram/img/guides/zapier/upload-openAPI.png new file mode 100644 index 00000000..b89c8483 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/upload-openAPI.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/zapier-create.png b/public/assets/docs/gram/img/guides/zapier/zapier-create.png new file mode 100644 index 00000000..d7dd79c5 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/zapier-create.png differ diff --git a/public/assets/docs/gram/img/guides/zapier/zapier-gram-account.png b/public/assets/docs/gram/img/guides/zapier/zapier-gram-account.png new file mode 100644 index 00000000..10d855cd Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/zapier-gram-account.png differ