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..b36711ba --- /dev/null +++ b/docs/gram/clients/using-zapier-with-gram-mcp-server.mdx @@ -0,0 +1,186 @@ +# 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 will show you how to connect Zapier to a Gram-hosted MCP server using the example Push Advisor API. You'll learn how to set up the connection and create a Zap that will interact with you in a Slack channel and use custom tools to check if 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](#connecting-zapier-to-your-gram-hosted-mcp-server). + +### Setting up a Gram project + +In the [Gram dashboard](https://app.getgram.ai), click **Get Started** and then **Start from API**. + +![get-started](assets/docs/gram/img/guides/zapier/get-started.png) + +### 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 (e.g. `push_advisor`) and click **Continue**. This will generate tools from your OpenAPI document. + +![name-toolset](assets/docs/gram/img/guides/zapier/name-toolset.png) + +Note the names of the tools that have been extracted from the OpenAPI document. + +### Step 3: Configure MCP + +Enter a URL slug for the MCP server (e.g., `zapier-push-advisor`) and click **Continue**. + +![mcp-slug](assets/docs/gram/img/guides/zapier/mcp-slug.png) + +This will finalize the creation of the toolset from the OpenAPI document. + +### Step 4: Test the toolset + +We can test that our tools are working correctly using the **Gram Playground**. Navigate to the **Playground** page and you will see a chatbot page with all our available tools listed on the left. + +Ask some questions in the chat that would trigger tool calls. For example, "Can I push to prod?". + +The AI will determine the correct tool to call and return 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 will 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 (e.g. `https://app.getgram.ai/mcp/zapier-push-advisor`) which we will use, along with our API key, to integrate with Zapier. + +## Creating a Zap with Gram MCP + +Let's create a Zap that will interact with our user through Slack and make use of our MCP toolset. + +To get started, sign into your Zapier account and press **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, send a message in your Slack channel that we can use for the remaining setup (e.g. "Should I push?"). Then test the trigger, select the message you sent from the detected list, and then click **Continue with select 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 event and click **Continue**. +![mcp-client](assets/docs/gram/img/guides/zapier/mcp-client.png) + +Click **Sign in** under **Account** and enter your **Server URL** and **Bearer Token** (this will be the API key that we copied from Gram earlier). Set Transport to **Streamable HTTP** and OAuth to **No**, then click **Yes, Continue to MCP Client**. + +![zapier-gram-account](assets/docs/gram/img/guides/zapier/zapier-gram-account.png) + +In the **Action** section, click the **Tool Name** dropdown to load the list of tools from your Gram server. Select the `should_i_push` 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 our Gram server is connected press the **+** 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 will be 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 your preferred **Model**. Then, 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 that is returned from our 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 give us 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, a reasonably strong prompt could be: + +``` +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 us an estimation on how strong it thinks our prompt is, and allows us to generate a sample response so we can see if we are satisfied with the behaviour. Once you are 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 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 will ensure that our trigger action does not kick off for the bot message, 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 to something relevant and then hit **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. + +**Explore more tools**: Add more tools to your Gram toolset and they will 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..67fe0b64 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..4b7db35e 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..d40d6b8b 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..dea3633a 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..0613fdee 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..9d0c3d7c 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..54d98bbe 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..ec0e08f9 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..306dfaa2 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..40493795 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..67715a49 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..ed5dd8d1 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..c65ab182 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..cd5a0eee 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..4de89f77 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..0e52cb71 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..7fdc8c7f 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..770dfe27 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..826ad8f3 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..602811b2 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..de89da28 Binary files /dev/null and b/public/assets/docs/gram/img/guides/zapier/zapier-gram-account.png differ