# create\_idea

Create an idea. Requires mcp:write and the existing ConversionLab idea create policy.

Create an idea. Requires mcp:write and the existing ConversionLab idea create policy.

## Permissions

```json
{
  "ability": "mcp:write",
  "role": "The existing entity create/update policy must allow this user; write ability alone is insufficient.",
  "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.",
  "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant."
}
```

## Input

```json
{
  "properties": {
    "project_id": {
      "description": "Project ID",
      "type": "integer"
    },
    "name": {
      "description": "Idea name",
      "maxLength": 255,
      "type": "string"
    },
    "state_id": {
      "description": "Optional idea state ID",
      "type": "integer"
    },
    "source": {
      "description": "Optional source type",
      "type": "string"
    },
    "source_name": {
      "description": "Optional source label",
      "type": "string"
    },
    "description": {
      "description": "Optional description",
      "type": "string"
    },
    "hypothesis": {
      "description": "Optional hypothesis",
      "type": "string"
    },
    "audience_ids": {
      "description": "Optional audience IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "experiment_ids": {
      "description": "Optional experiment IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "insight_ids": {
      "description": "Optional insight IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "metric_ids": {
      "description": "Optional metric IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "page_ids": {
      "description": "Optional page IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "priority_values": {
      "description": "Optional prioritization values keyed by input variable, for example {\"impact\": 5, \"confidence\": 8, \"effort\": 2}",
      "type": [
        "object",
        "null"
      ]
    }
  },
  "type": "object",
  "required": [
    "project_id",
    "name"
  ]
}
```

## Output

```json
{
  "type": "object",
  "properties": {
    "created": {
      "type": "boolean",
      "const": true
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "project_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "name": {
          "type": "string"
        },
        "state_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "source": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "audit",
            "insight",
            "experiment",
            "form",
            "api",
            null
          ]
        },
        "source_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "priority_score": {
          "type": [
            "number",
            "string",
            "null"
          ],
          "description": "A decimal may be serialized as a string."
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "project": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "hypothesis": {
          "type": [
            "string",
            "null"
          ]
        },
        "priority_values": {
          "type": [
            "object",
            "array",
            "null"
          ],
          "additionalProperties": true,
          "items": true,
          "description": "Stored JSON values, usually keyed by the prioritization model variable."
        },
        "priority_details": {
          "type": [
            "object",
            "array",
            "null"
          ],
          "additionalProperties": true,
          "items": true
        },
        "state": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "audiences": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          }
        },
        "experiments": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          }
        },
        "insights": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          }
        },
        "metrics": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          }
        },
        "pages": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          }
        }
      },
      "required": [
        "id",
        "project_id",
        "name",
        "state_id",
        "source",
        "source_name",
        "priority_score",
        "created_at",
        "updated_at",
        "description",
        "project",
        "hypothesis",
        "priority_values",
        "priority_details",
        "state",
        "audiences",
        "experiments",
        "insights",
        "metrics",
        "pages"
      ]
    }
  },
  "required": [
    "created",
    "data"
  ]
}
```

## Examples

### Request arguments

```json
{
  "project_id": 1,
  "name": "Explain delivery times at checkout"
}
```

### Result

```json
{
  "created": true,
  "data": {
    "id": 101,
    "project_id": 1,
    "state_id": null,
    "name": "Explain delivery times at checkout",
    "source": "audit",
    "source_name": null,
    "priority_score": null,
    "created_at": "2026-01-15T12:00:00+00:00",
    "updated_at": "2026-01-15T12:00:00+00:00",
    "description": null,
    "hypothesis": null,
    "priority_values": null,
    "priority_details": null,
    "project": null,
    "state": null,
    "audiences": [],
    "experiments": [],
    "insights": [],
    "metrics": [],
    "pages": []
  }
}
```

## Errors

```json
[
  {
    "status": 401,
    "description": "Missing, expired, or revoked bearer token."
  },
  {
    "status": 403,
    "description": "Missing MCP ability, team membership, plan entitlement, or user permission."
  },
  {
    "status": 404,
    "description": "The MCP server is disabled."
  },
  {
    "status": 429,
    "description": "Rate limited; honor Retry-After before retrying."
  },
  {
    "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call."
  }
]
```

An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication).