MCP Gateway Examples

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": "colleague@example.com",
      "body": "Let's meet at 2pm..."
    }
  },
  {
    "status_code": 200,
    "response_content": {
      "id": "msg_002",
      "subject": "Project Update",
      "from": "manager@example.com",
      "body": "Here's the latest update..."
    }
  },
  {
    "status_code": 200,
    "response_content": {
      "id": "msg_003",
      "subject": "Action Required",
      "from": "system@example.com",
      "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": "sender@example.com"
        }
      }
    },
    {
      "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.

​Overview

​Example 1: Discovering and Executing an Action

​Step 1: Discover Available Actions

​Step 2: Get Full Action Details

​Step 3: Execute the Action

​Example 2: Searching for Actions

​Search for Message-Related Actions

​Get Details and Execute

​Example 3: Batch Execution

​Reading Multiple Emails

​Example 4: Parallel Multi-Action Execution

​Fetching Data from Multiple Sources

​Example 5: Using Response Projection

​Extract Specific Fields from Large Response

​Filter and Aggregate Data

​Example 6: Agent Mode - Getting Instructions

​Retrieve Agent Instructions

​Example 7: Agent Mode - Listing Applications

​Get All Apps with Action Summaries

​Example 8: Agent Mode - Context Management

​List All Contexts

​Search for Specific Contexts

​Get Context Details

​Create New Context

​Example 9: Complete Workflow

​Multi-Step Workflow Example

​Best Practices

​1. Use Summary Mode for Discovery

​2. Get Full Schemas Before Execution

​3. Use Batch Operations for Efficiency

​4. Leverage Parallel Execution

​5. Use Response Projection for Large Data

​Common Patterns

​Pattern: Discover → Get Details → Execute

​Pattern: Search → Execute

​Pattern: Batch Processing

​Next Steps

Overview

Example 1: Discovering and Executing an Action

Step 1: Discover Available Actions

Step 2: Get Full Action Details

Step 3: Execute the Action

Example 2: Searching for Actions

Search for Message-Related Actions

Get Details and Execute

Example 3: Batch Execution

Reading Multiple Emails

Example 4: Parallel Multi-Action Execution

Fetching Data from Multiple Sources

Example 5: Using Response Projection

Extract Specific Fields from Large Response

Filter and Aggregate Data

Example 6: Agent Mode - Getting Instructions

Retrieve Agent Instructions

Example 7: Agent Mode - Listing Applications

Get All Apps with Action Summaries

Example 8: Agent Mode - Context Management

List All Contexts

Search for Specific Contexts

Get Context Details

Create New Context

Example 9: Complete Workflow

Multi-Step Workflow Example

Best Practices

1. Use Summary Mode for Discovery

2. Get Full Schemas Before Execution

3. Use Batch Operations for Efficiency

4. Leverage Parallel Execution

5. Use Response Projection for Large Data

Common Patterns

Pattern: Discover → Get Details → Execute

Pattern: Search → Execute

Pattern: Batch Processing

Next Steps