portkey-admin-mcp

create_mcp_integration

Creates a Portkey integration for an external MCP server URL, including header or OAuth authentication and runtime secret mappings, and returns the integration ID and slug.

Instructions

Create a Portkey integration for an external MCP server URL. For headers auth, provide custom_headers or a Secret Reference mapping targeting configurations.custom_headers; secret_mappings resolve protected values at runtime without storing them in the tool call. Organisation admin keys normally need workspace_id. After creation, create_mcp_server and configure capabilities/access; returns the integration id and slug.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>",
      "url": "<url>",
      "auth_type": "<auth_type>",
      "transport": "<transport>"
    },
    "name": "create_mcp_integration"
  }
}

Input Schema

Name	Required	Description
`url`	Yes	URL endpoint of the MCP server to integrate
`name`	Yes	Display name for the MCP integration
`slug`	No	Custom slug. Auto-generated if omitted
`auth_type`	Yes	Authentication type. Current examples are 'none', 'headers' (custom headers), and 'oauth_auto' (OAuth); Portkey may accept additional values.
`transport`	Yes	MCP transport protocol: 'http' (streamable HTTP) or 'sse' (server-sent events)
`description`	No	Description of the MCP integration
`workspace_id`	No	Workspace ID — required when using organization admin API keys
`configurations`	No	Additional documented or forward-compatible configuration fields. For headers auth, configurations.custom_headers is a string-to-string header map.
`custom_headers`	No	Custom headers for authentication (e.g. { "Authorization": "Bearer xxx" }). Sent via configurations.custom_headers
`secret_mappings`	No	Runtime Secret Reference mappings; every configurations.<field> target must be unique

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"

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 changedv0.11.5Sep 8, 2026

changedInput schema / properties / auth_type / description

Previous value: -"Authentication type: 'none', 'headers' (custom headers), or 'oauth_auto' (OAuth)"New value: +"Authentication type. Current examples are 'none', 'headers' (custom headers), and 'oauth_auto' (OAuth); Portkey may accept additional values."

removedInput schema / properties / auth_type / enum

Removed value: -[
-  "oauth_auto",
-  "headers",
-  "none"
-]

addedInput schema / properties / auth_type / minLength
```
Added value: +1
```

addedInput schema / properties / configurations

Added value: +{
+  "additionalProperties": {},
+  "description": "Additional documented or forward-compatible configuration fields. For headers auth, configurations.custom_headers is a string-to-string header map.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

Changed1 schema field changedAug 9, 2026

addedInput schema / properties / secret_mappings

Added value: +{
+  "description": "Runtime Secret Reference mappings; every configurations.<field> target must be unique",
+  "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 this integration",
+        "type": "string"
+      },
+      "target_field": {
+        "description": "Configuration field resolved at runtime, such as configurations.oauth_metadata",
+        "type": "string"
+      },
+      "value_format": {
+        "anyOf": [
+          {
+            "enum": [
+              "string",
+              "json"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Use json when the target configuration field expects a structured object"
+      }
+    },
+    "required": [
+      "target_field",
+      "secret_reference_id"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Addedv1.0.1May 7, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Beyond the annotations (non-read-only, non-destructive, non-idempotent, open-world), it discloses two things an agent cannot infer: secret_mappings resolve protected values at runtime rather than being stored in the call, and the tool returns the integration id and slug for chaining. It does not discuss failure modes or what happens on duplicate names/slugs, but the annotations already carry most of the safety profile.

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?

Four dense sentences, front-loaded with the core action and then auth, workspace, and post-creation sequencing. Every sentence carries information, though the auth sentence is packed with three distinct ideas and could have been split for scanability.

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

Completeness5/5

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

For a 10-parameter, nested-object, open-world creation tool with full schema coverage and an output schema, the description supplies exactly the missing connective tissue: the two auth patterns, the org-admin workspace caveat, and the mandatory follow-up calls. Return values are already covered by the output schema, so nothing material is absent.

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 goes slightly beyond by clarifying the routing relationship between custom_headers and configurations.custom_headers and by framing secret_mappings as runtime-resolved targets against configurations.<field>. It still leaves value_format and secret_key selection entirely to the schema, so it is an increment rather than a full semantic layer.

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

Purpose5/5

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

The first sentence gives a specific verb and resource — creating a Portkey integration that points at an external MCP server URL — which cleanly separates it from the sibling create_integration (LLM provider) and from create_mcp_server, which the description explicitly names as the follow-up step. An agent can pick this tool out of the large sibling list without opening the schema.

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

Usage Guidelines4/5

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

It gives concrete conditional guidance: use custom_headers or a Secret Reference mapping for headers auth, and organisation admin keys 'normally need workspace_id'. It also sequences the workflow (create, then create_mcp_server and configure capabilities/access). It stops short of stating when to prefer update_mcp_integration over this tool or any exclusions, so it is clear context rather than a full when/when-not rule set.

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

Deploy Server