Skip to main content

​
Overview

This guide provides practical examples for common use cases with the MCP Gateway. All examples use standard MCP tool calling format.

​
Example 1: Discovering and Executing an Action

​
Step 1: Discover Available Actions

{
  "tool": "list_actions",
  "arguments": {
    "requests": [
      {
        "app_name": "Slack",
        "detail_level": "summary"
      }
    ]
  }
}
Response: 
[
  {
    "operationId": "chat.postMessage",
    "description": "Sends a message to a channel"
  },
  {
    "operationId": "conversations.list",
    "description": "Lists all channels in a Slack team"
  },
  {
    "operationId": "users.info",
    "description": "Gets information about a user"
  }
]

​
Step 2: Get Full Action Details

{
  "tool": "list_actions",
  "arguments": {
    "requests": [
      {
        "app_name": "Slack",
        "operationIds": ["chat.postMessage"]
      }
    ]
  }
}
Response: 
[
  {
    "operationId": "chat.postMessage",
    "description": "Sends a message to a channel",
    "parameters": {
      "channel": {
        "type": "string",
        "required": true,
        "description": "Channel, private group, or IM channel to send message to"
      },
      "text": {
        "type": "string",
        "required": true,
        "description": "Text of the message to send"
      },
      "thread_ts": {
        "type": "string",
        "required": false,
        "description": "Provide another message's ts value to make this message a reply"
      }
    }
  }
]

​
Step 3: Execute the Action

{
  "tool": "run_action",
  "arguments": {
    "app_name": "Slack",
    "user_input": "Send a message to the general channel",
    "context": {
      "operationId": "chat.postMessage",
      "channel": "#general",
      "text": "Hello from Apigene!"
    }
  }
}
Response: 
{
  "status_code": 200,
  "response_content": {
    "ok": true,
    "channel": "C1234567890",
    "ts": "1234567890.123456",
    "message": {
      "text": "Hello from Apigene!",
      "user": "U1234567890",
      "ts": "1234567890.123456"
    }
  }
}

​
Example 2: Searching for Actions

{
  "tool": "search_actions",
  "arguments": {
    "query": "send message",
    "detail_level": "summary",
    "max_results": 10
  }
}
Response: 
[
  {
    "app_name": "Slack",
    "operationId": "chat.postMessage",
    "description": "Sends a message to a channel",
    "rating": 4.8
  },
  {
    "app_name": "Microsoft Teams",
    "operationId": "sendMessage",
    "description": "Send a message to a channel or chat",
    "rating": 4.6
  },
  {
    "app_name": "Discord",
    "operationId": "createMessage",
    "description": "Create a message in a channel",
    "rating": 4.5
  }
]

​
Get Details and Execute

After finding the right action, get full details and execute: 
{
  "tool": "list_actions",
  "arguments": {
    "requests": [
      {
        "app_name": "Slack",
        "operationIds": ["chat.postMessage"]
      }
    ]
  }
}
Then execute with proper parameters.

​
Example 3: Batch Execution

​
Reading Multiple Emails

{
  "tool": "run_action_batch",
  "arguments": {
    "app_name": "Gmail",
    "user_input": "Read multiple emails",
    "base_context": {
      "operationId": "readEmail",
      "format": "full"
    },
    "batch_context": [
      { "email_id": "msg_001" },
      { "email_id": "msg_002" },
      { "email_id": "msg_003" }
    ]
  }
}
Response: 
[
  {
    "status_code": 200,
    "response_content": {
      "id": "msg_001",
      "subject": "Meeting Tomorrow",
      "from": "[email protected]",
      "body": "Let's meet at 2pm..."
    }
  },
  {
    "status_code": 200,
    "response_content": {
      "id": "msg_002",
      "subject": "Project Update",
      "from": "[email protected]",
      "body": "Here's the latest update..."
    }
  },
  {
    "status_code": 200,
    "response_content": {
      "id": "msg_003",
      "subject": "Action Required",
      "from": "[email protected]",
      "body": "Please review the attached..."
    }
  }
]

​
Example 4: Parallel Multi-Action Execution

​
Fetching Data from Multiple Sources

{
  "tool": "run_multi_actions",
  "arguments": {
    "actions": [
      {
        "app_name": "Gmail",
        "user_input": "Get latest email",
        "context": {
          "operationId": "getLatestEmail"
        }
      },
      {
        "app_name": "Jira",
        "user_input": "List my open issues",
        "context": {
          "operationId": "listIssues",
          "assignee": "me",
          "status": "open"
        }
      },
      {
        "app_name": "Slack",
        "user_input": "Get unread message count",
        "context": {
          "operationId": "getUnreadCount"
        }
      }
    ]
  }
}
Response: 
{
  "results": [
    {
      "success": true,
      "index": 0,
      "request": {
        "app_name": "Gmail",
        "user_input": "Get latest email",
        "context": {
          "operationId": "getLatestEmail"
        }
      },
      "result": {
        "status_code": 200,
        "response_content": {
          "id": "msg_123",
          "subject": "Latest Email Subject",
          "from": "[email protected]"
        }
      }
    },
    {
      "success": true,
      "index": 1,
      "request": {
        "app_name": "Jira",
        "user_input": "List my open issues",
        "context": {
          "operationId": "listIssues",
          "assignee": "me",
          "status": "open"
        }
      },
      "result": {
        "status_code": 200,
        "response_content": {
          "issues": [
            {"id": "PROJ-123", "summary": "Fix bug"},
            {"id": "PROJ-124", "summary": "Add feature"}
          ]
        }
      }
    },
    {
      "success": true,
      "index": 2,
      "request": {
        "app_name": "Slack",
        "user_input": "Get unread message count",
        "context": {
          "operationId": "getUnreadCount"
        }
      },
      "result": {
        "status_code": 200,
        "response_content": {
          "unread_count": 5
        }
      }
    }
  ],
  "summary": {
    "total": 3,
    "successful": 3,
    "failed": 0
  }
}

​
Example 5: Using Response Projection

​
Extract Specific Fields from Large Response

{
  "tool": "run_action",
  "arguments": {
    "app_name": "Jira",
    "user_input": "List all issues",
    "context": {
      "operationId": "listIssues"
    },
    "response_projection": "{issues: issues[*].{id: id, key: key, summary: fields.summary, status: fields.status.name}}"
  }
}
Response: 
{
  "status_code": 200,
  "response_content": {
    "issues": [
      {
        "id": "10001",
        "key": "PROJ-123",
        "summary": "Fix login bug",
        "status": "In Progress"
      },
      {
        "id": "10002",
        "key": "PROJ-124",
        "summary": "Add dark mode",
        "status": "To Do"
      }
    ]
  }
}

​
Filter and Aggregate Data

{
  "tool": "run_action",
  "arguments": {
    "app_name": "Salesforce",
    "user_input": "Get high-value opportunities",
    "context": {
      "operationId": "listOpportunities"
    },
    "response_projection": "opportunities[?amount > 10000].{name: name, amount: amount, stage: stageName}"
  }
}
Response: 
{
  "status_code": 200,
  "response_content": {
    "opportunities": [
      {
        "name": "Enterprise Deal",
        "amount": 50000,
        "stageName": "Negotiation"
      },
      {
        "name": "SMB Contract",
        "amount": 15000,
        "stageName": "Proposal"
      }
    ]
  }
}

​
Example 6: Agent Mode - Getting Instructions

​
Retrieve Agent Instructions

{
  "tool": "get_instructions",
  "arguments": {}
}
Response: 
"You are a helpful AI assistant that can interact with various applications including Slack, Gmail, and Jira. Your capabilities include:

- Sending messages and notifications
- Reading and managing emails
- Creating and tracking issues
- Searching across multiple data sources

Available applications: Slack, Gmail, Jira, GitHub

Guidelines:
- Always confirm before executing destructive actions
- Provide clear summaries of actions taken
- Ask for clarification when parameters are ambiguous"

​
Example 7: Agent Mode - Listing Applications

​
Get All Apps with Action Summaries

{
  "tool": "list_available_apps",
  "arguments": {
    "include_action_summaries": true,
    "max_action_summary": 20
  }
}
Response: 
[
  {
    "app_name": "Slack",
    "action_summaries": [
      {
        "operationId": "chat.postMessage",
        "description": "Sends a message to a channel"
      },
      {
        "operationId": "conversations.list",
        "description": "Lists all channels"
      }
    ]
  },
  {
    "app_name": "Gmail",
    "action_summaries": [
      {
        "operationId": "readEmail",
        "description": "Reads an email by ID"
      },
      {
        "operationId": "listEmails",
        "description": "Lists emails in inbox"
      }
    ]
  }
]

​
Example 8: Agent Mode - Context Management

​
List All Contexts

{
  "tool": "list_contexts",
  "arguments": {}
}
Response: 
{
  "contexts": [
    {
      "id": "ctx_123",
      "name": "Customer Support Knowledge",
      "type": "Knowledge",
      "summary": "Support policies and procedures"
    },
    {
      "id": "ctx_456",
      "name": "Product Information",
      "type": "Knowledge",
      "summary": "Product features and specifications"
    }
  ],
  "context_types": [
    {
      "type": "Knowledge",
      "description": "Structured knowledge base information"
    },
    {
      "type": "Instructions",
      "description": "Agent instructions and guidelines"
    }
  ]
}

​
Search for Specific Contexts

{
  "tool": "search_contexts",
  "arguments": {
    "query": "customer support",
    "type": "Knowledge",
    "max_results": 5
  }
}
Response: 
{
  "contexts": [
    {
      "id": "ctx_123",
      "name": "Customer Support Knowledge",
      "type": "Knowledge",
      "summary": "Support policies and procedures"
    }
  ],
  "context_types": [...]
}

​
Get Context Details

{
  "tool": "get_context",
  "arguments": {
    "context_id": "ctx_123"
  }
}
Response: 
{
  "id": "ctx_123",
  "name": "Product Knowledge Base",
  "description": "Comprehensive information about our products...",
  "summary": "Product information and features",
  "type": "Knowledge",
  "apps": ["Salesforce", "Zendesk"],
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

​
Create New Context

{
  "tool": "add_context",
  "arguments": {
    "name": "Product Knowledge Base",
    "description": "Comprehensive information about our products, features, and pricing...",
    "summary": "Product information and features",
    "type": "Knowledge",
    "apps": ["Salesforce", "Zendesk"],
    "status": "active"
  }
}
Response: 
{
  "id": "ctx_789",
  "name": "Product Knowledge Base",
  "description": "Comprehensive information about our products, features, and pricing...",
  "summary": "Product information and features",
  "type": "Knowledge",
  "apps": ["Salesforce", "Zendesk"],
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "_message": "Context created successfully and added to agent 'MyAgent'"
}

​
Example 9: Complete Workflow

​
Multi-Step Workflow Example

Step 1: Discover available actions 
{
  "tool": "list_actions",
  "arguments": {
    "requests": [
      { "app_name": "GitHub", "detail_level": "summary" },
      { "app_name": "Slack", "detail_level": "summary" }
    ]
  }
}
Step 2: Get full details for specific actions 
{
  "tool": "list_actions",
  "arguments": {
    "requests": [
      {
        "app_name": "GitHub",
        "operationIds": ["createIssue"]
      },
      {
        "app_name": "Slack",
        "operationIds": ["chat.postMessage"]
      }
    ]
  }
}
Step 3: Execute actions in sequence or parallel 
{
  "tool": "run_multi_actions",
  "arguments": {
    "actions": [
      {
        "app_name": "GitHub",
        "user_input": "Create a new issue",
        "context": {
          "operationId": "createIssue",
          "title": "Bug: Login not working",
          "body": "Users cannot log in..."
        }
      },
      {
        "app_name": "Slack",
        "user_input": "Notify team about new issue",
        "context": {
          "operationId": "chat.postMessage",
          "channel": "#engineering",
          "text": "New GitHub issue created: Bug: Login not working"
        }
      }
    ]
  }
}
Step 1 Response: 
{
  "GitHub": [
    {
      "operationId": "createIssue",
      "description": "Create a new issue in a repository"
    },
    {
      "operationId": "listIssues",
      "description": "List issues in a repository"
    }
  ],
  "Slack": [
    {
      "operationId": "chat.postMessage",
      "description": "Sends a message to a channel"
    }
  ]
}
Step 2 Response: 
[
  {
    "operationId": "createIssue",
    "description": "Create a new issue in a repository",
    "parameters": {
      "title": {"type": "string", "required": true},
      "body": {"type": "string", "required": false},
      "labels": {"type": "array", "required": false}
    }
  },
  {
    "operationId": "chat.postMessage",
    "description": "Sends a message to a channel",
    "parameters": {
      "channel": {"type": "string", "required": true},
      "text": {"type": "string", "required": true}
    }
  }
]
Step 3 Response: 
{
  "results": [
    {
      "success": true,
      "index": 0,
      "request": {
        "app_name": "GitHub",
        "user_input": "Create a new issue",
        "context": {
          "operationId": "createIssue",
          "title": "Bug: Login not working",
          "body": "Users cannot log in..."
        }
      },
      "result": {
        "status_code": 201,
        "response_content": {
          "id": 12345,
          "number": 42,
          "title": "Bug: Login not working",
          "state": "open",
          "url": "https://github.com/owner/repo/issues/42"
        }
      }
    },
    {
      "success": true,
      "index": 1,
      "request": {
        "app_name": "Slack",
        "user_input": "Notify team about new issue",
        "context": {
          "operationId": "chat.postMessage",
          "channel": "#engineering",
          "text": "New GitHub issue created: Bug: Login not working"
        }
      },
      "result": {
        "status_code": 200,
        "response_content": {
          "ok": true,
          "channel": "C1234567890",
          "ts": "1234567890.123456",
          "message": {
            "text": "New GitHub issue created: Bug: Login not working"
          }
        }
      }
    }
  ],
  "summary": {
    "total": 2,
    "successful": 2,
    "failed": 0
  }
}

​
Best Practices

​
1. Use Summary Mode for Discovery

Always start with detail_level: "summary" when exploring actions to save tokens and improve performance.

​
2. Get Full Schemas Before Execution

Always call list_actions with specific operationIds to get complete parameter specifications before executing actions.

​
3. Use Batch Operations for Efficiency

When executing the same action multiple times, use run_action_batch instead of multiple run_action calls.

​
4. Leverage Parallel Execution

Use run_multi_actions when you need to fetch data from multiple sources simultaneously.

​
5. Use Response Projection for Large Data

Apply response_projection to reduce response size when you only need specific fields from large responses.

​
Common Patterns

​
Pattern: Discover → Get Details → Execute

  1. Use list_actions with detail_level: "summary" to discover
  2. Use list_actions with operationIds to get full schemas
  3. Use run_action with complete parameters to execute

​
Pattern: Search → Execute

  1. Use search_actions to find relevant actions
  2. Get full details for selected actions
  3. Execute with proper parameters

​
Pattern: Batch Processing

  1. Identify the action to execute multiple times
  2. Prepare base_context with shared parameters
  3. Prepare batch_context with varying parameters
  4. Execute with run_action_batch

​
Next Steps