> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apigene.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Gateway Examples

> Practical examples for using the MCP Gateway

## 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

```json theme={null}
{
  "tool": "list_actions",
  "arguments": {
    "requests": [
      {
        "app_name": "Slack",
        "detail_level": "summary"
      }
    ]
  }
}
```

**Response:**

```json theme={null}
[
  {
    "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

```json theme={null}
{
  "tool": "list_actions",
  "arguments": {
    "requests": [
      {
        "app_name": "Slack",
        "operationIds": ["chat.postMessage"]
      }
    ]
  }
}
```

**Response:**

```json theme={null}
[
  {
    "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

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

### Search for Message-Related Actions

```json theme={null}
{
  "tool": "search_actions",
  "arguments": {
    "query": "send message",
    "detail_level": "summary",
    "max_results": 10
  }
}
```

**Response:**

```json theme={null}
[
  {
    "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:

```json theme={null}
{
  "tool": "list_actions",
  "arguments": {
    "requests": [
      {
        "app_name": "Slack",
        "operationIds": ["chat.postMessage"]
      }
    ]
  }
}
```

Then execute with proper parameters.

## Example 3: Batch Execution

### Reading Multiple Emails

```json theme={null}
{
  "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:**

```json theme={null}
[
  {
    "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

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

```json theme={null}
{
  "tool": "get_instructions",
  "arguments": {}
}
```

**Response:**

```json theme={null}
"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

```json theme={null}
{
  "tool": "list_available_apps",
  "arguments": {
    "include_action_summaries": true,
    "max_action_summary": 20
  }
}
```

**Response:**

```json theme={null}
[
  {
    "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

```json theme={null}
{
  "tool": "list_contexts",
  "arguments": {}
}
```

**Response:**

```json theme={null}
{
  "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

```json theme={null}
{
  "tool": "search_contexts",
  "arguments": {
    "query": "customer support",
    "type": "Knowledge",
    "max_results": 5
  }
}
```

**Response:**

```json theme={null}
{
  "contexts": [
    {
      "id": "ctx_123",
      "name": "Customer Support Knowledge",
      "type": "Knowledge",
      "summary": "Support policies and procedures"
    }
  ],
  "context_types": [...]
}
```

### Get Context Details

```json theme={null}
{
  "tool": "get_context",
  "arguments": {
    "context_id": "ctx_123"
  }
}
```

**Response:**

```json theme={null}
{
  "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

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "tool": "list_actions",
  "arguments": {
    "requests": [
      {
        "app_name": "GitHub",
        "operationIds": ["createIssue"]
      },
      {
        "app_name": "Slack",
        "operationIds": ["chat.postMessage"]
      }
    ]
  }
}
```

**Step 3:** Execute actions in sequence or parallel

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
[
  {
    "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:**

```json theme={null}
{
  "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

* [Review all available tools](/user-guide/mcp-gateway/mcp-gateway-tools)
* [Learn about resources](/user-guide/mcp-gateway/mcp-gateway-resources)