portkey-admin-mcp

create_integration

Creates an AI-provider integration that serves as the source for workspace providers, configuring provider credentials, hosts, secret mappings, and pricing adjustments.

Instructions

Create an AI-provider integration that becomes the source for workspace providers. ai_provider_id identifies the backend; provider-specific fields configure Azure, Bedrock, Vertex, or custom hosts. For workspace-scoped integrations, create_default_provider controls automatic provider creation. key is write-only, but secret_mappings can resolve it or configuration fields from Secret References at runtime. pricing_adjustments apply negotiated discounts or markups to cost accounting; tags attach key-value labels that list_integrations can filter on. Use update_integration_models and update_integration_workspaces after creation; returns the new integration id and slug.

Input Schema

Name	Required	Description
`key`	No	API key for the provider (if required)
`name`	Yes	Human-readable name for the integration
`slug`	No	URL-friendly identifier (auto-generated from name if not provided)
`tags`	No	Integration tags, or null to create without tags
`aws_region`	No	AWS region (for AWS Bedrock)
`api_version`	No	API version (for Azure OpenAI)
`custom_host`	No	Custom base URL for the provider
`description`	No	Optional description of the integration
`workspace_id`	No	Workspace ID for workspace-scoped integrations
`resource_name`	No	Resource name (for Azure OpenAI)
`vertex_region`	No	GCP region (for Vertex AI)
`ai_provider_id`	Yes	ID of the AI provider (e.g., 'openai', 'anthropic', 'azure-openai', 'aws-bedrock', 'vertex-ai')
`deployment_name`	No	Deployment name (for Azure OpenAI)
`secret_mappings`	No	Unique runtime Secret Reference mappings; mapping key allows the key field to be omitted
`aws_access_key_id`	No	AWS access key ID (for AWS Bedrock)
`vertex_project_id`	No	GCP project ID (for Vertex AI)
`pricing_adjustments`	No	Negotiated discount or markup multipliers for cost accounting
`aws_secret_access_key`	No	AWS secret access key (for AWS Bedrock)
`default_provider_slug`	No	Custom slug for the automatically created workspace provider
`create_default_provider`	No	Create a provider automatically for a workspace-scoped integration; defaults to true

Output Schema

Name	Required	Description
`ok`	Yes	Whether the tool call succeeded and returned structured data
`data`	No	Structured success payload when ok is true
`error`	No	Structured error payload when ok is false

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.0.9Oct 26, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedv0.13.0Oct 3, 2026

addedInput schema / properties / tags

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Integration tags, or null to create without tags"
+}

Changed2 schema fields changedv0.12.2Oct 2, 2026
- removedInput schema / properties / secret_mappings / items / properties / secret_key / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedInput schema / properties / secret_mappings / items / properties / secret_key / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed4 schema fields changedAug 9, 2026

addedInput schema / properties / create_default_provider

Added value: +{
+  "description": "Create a provider automatically for a workspace-scoped integration; defaults to true",
+  "type": "boolean"
+}

addedInput schema / properties / default_provider_slug

Added value: +{
+  "description": "Custom slug for the automatically created workspace provider",
+  "maxLength": 255,
+  "pattern": "^[a-zA-Z0-9_-]+$",
+  "type": "string"
+}

addedInput schema / properties / pricing_adjustments

Added value: +{
+  "anyOf": [
+    {
+      "properties": {
+        "multiplier": {
+          "description": "Per-unit multipliers applied over Portkey catalog pricing",
+          "properties": {
+            "additional_units": {
+              "anyOf": [
+                {
+                  "additionalProperties": {
+                    "anyOf": [
+                      {
+                        "minimum": 0,
+                        "type": "number"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Multipliers keyed by Portkey pricing unit, such as web_search or file_search"
+            },
+            "cache_read_audio_input_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Cache-read audio input token price multiplier"
+            },
+            "cache_read_image_input_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Cache-read image input token price multiplier"
+            },
+            "cache_read_input_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Cache-read input token price multiplier"
+            },
+            "cache_read_text_input_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Cache-read text input token price multiplier"
+            },
+            "cache_write_image_input_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Cache-write image input token price multiplier"
+            },
+            "cache_write_input_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Cache-write input token price multiplier"
+            },
+            "cache_write_text_input_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Cache-write text input token price multiplier"
+            },
+            "default": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Fallback multiplier for pricing units; 1 is unchanged, 0.8 is a 20% discount"
+            },
+            "image": {
+              "anyOf": [
+                {
+                  "properties": {
+                    "default": {
+                      "anyOf": [
+                        {
+                          "minimum": 0,
+                          "type": "number"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "Default image-generation price multiplier"
+                    }
+                  },
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Image-generation pricing multipliers"
+            },
+            "prediction_accepted_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Accepted predicted-output token price multiplier"
+            },
+            "prediction_rejected_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Rejected predicted-output token price multiplier"
+            },
+            "reasoning_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Reasoning token price multiplier"
+            },
+            "request_audio_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Audio input token price multiplier"
+            },
+            "request_image_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Image input token price multiplier"
+            },
+            "request_text_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Text input token price multiplier"
+            },
+            "request_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Input token price multiplier"
+            },
+            "response_audio_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Audio output token price multiplier"
+            },
+            "response_image_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Image output token price multiplier"
+            },
+            "response_text_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Text output token price multiplier"
+            },
+            "response_token": {
+              "anyOf": [
+                {
+                  "minimum": 0,
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Output token price multiplier"
+            }
+          },
+          "type": "object"
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Negotiated discount or markup multipliers for cost accounting"
+}

addedInput schema / properties / secret_mappings

Added value: +{
+  "description": "Unique runtime Secret Reference mappings; mapping key allows the key field to be omitted",
+  "items": {
+    "properties": {
+      "secret_key": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Optional key to select from a multi-value secret"
+      },
+      "secret_reference_id": {
+        "description": "Secret Reference UUID or slug accessible to the workspace",
+        "type": "string"
+      },
+      "target_field": {
+        "description": "Integration field populated at runtime: key or configurations.<field>",
+        "type": "string"
+      },
+      "value_format": {
+        "anyOf": [
+          {
+            "enum": [
+              "string",
+              "json"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Treat the resolved value as a plain string or parsed JSON"
+      }
+    },
+    "required": [
+      "target_field",
+      "secret_reference_id"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Addedv1.0.1May 7, 2026
RemovedMay 1, 2026
First observedJan 1, 2026

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations already covering safety (readOnly=false, destructive=false, idempotent=false, openWorld=true), the description adds real context: key is write-only, secret_mappings resolve values at runtime, create_default_provider defaults to true, and the return value (new id and slug). It omits auth/permission requirements and duplicate-name conflict behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense paragraph with no filler sentences; the scoping statement is front-loaded and follow-up tools are last. It is slightly run-on, packing provider fields, defaults, secrets, pricing, tags and next steps into a single block without visual grouping.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter creation tool with an output schema (so return values needn't be described), it covers the default behavior, conditional provider fields, secrets substitution and follow-up mutations. Missing only failure modes and permission/scope constraints, which an agent creating integrations would benefit from.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3; the description earns above that by grouping the provider-specific fields (Azure/Bedrock/Vertex/custom hosts) semantically, explaining ai_provider_id's role as backend selector, and noting that tags feed list_integrations filtering and that secret_mappings can substitute for key.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource plus a role statement ('becomes the source for workspace providers'), which separates it from create_provider/list_integrations. The distinction from create_provider is implied through 'source for workspace providers' rather than named explicitly, keeping it just below top marks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit post-creation sequencing ('Use update_integration_models and update_integration_workspaces after creation'), but never states when to choose this over create_provider or list_integrations, nor any prerequisites or exclusions. Usage is implied rather than routed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server