alterlab-mcp-server

alterlab_create_session

Create a reusable authenticated scraping session by storing browser login cookies, so scrapes can access login-walled pages. Requires explicit consent; returns a session_id for reuse.

Instructions

Create a new stored session for authenticated scraping. Provide cookies from a logged-in browser session to enable scraping behind login walls. The session is stored securely and can be reused across multiple scrape requests via session_id. Requires consent=true (explicit GDPR consent to store the cookies); optional headers, expires_at, notes, auto_refresh/notification flags and organization sharing are supported.

Input Schema

Name	Required	Description
`name`	Yes	Human-readable name for this session (e.g., 'My Amazon Account')
`notes`	No	Free-text notes about this session
`domain`	Yes	Domain this session is for (e.g., 'amazon.com')
`shared`	No	Share the session with organization members immediately (API default false)
`consent`	Yes	Explicit GDPR consent from the account owner to store these session cookies. Must be true — the API rejects session creation with CONSENT_REQUIRED otherwise. Only set true after the user has agreed to AlterLab storing their cookies.
`cookies`	No	Cookies for authentication. Cookies as a {name: value} object (e.g. {"session-id": "abc123"}) or as a list (max 100) of cookie objects with metadata: {name, value, domain?, path?, secure?, httpOnly?, sameSite?, expires?}.
`headers`	No	Custom headers sent with this session (e.g., a User-Agent or Authorization header)
`expires_at`	No	Session expiry in ISO 8601 format (e.g., '2026-12-31T23:59:59Z')
`organization_id`	No	Organization to assign the session to (org admins only)
`notify_on_failure`	No	Notify when session validation fails (API default true)
`auto_refresh_enabled`	No	Enable proactive expiry detection and health checks (API default true)
`notify_before_expiry`	No	Notify when the session is about to expire (API default true)

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedv1.9.0Oct 16, 2026

addedInput schema / properties / auto_refresh_enabled

Added value: +{
+  "description": "Enable proactive expiry detection and health checks (API default true)",
+  "type": "boolean"
+}

addedInput schema / properties / consent

Added value: +{
+  "description": "Explicit GDPR consent from the account owner to store these session cookies. Must be true — the API rejects session creation with CONSENT_REQUIRED otherwise. Only set true after the user has agreed to AlterLab storing their cookies.",
+  "type": "boolean"
+}

removedInput schema / properties / cookies / additionalProperties
```
Removed value: -{
-  "type": "string"
-}
```

addedInput schema / properties / cookies / anyOf

Added value: +[
+  {
+    "additionalProperties": {
+      "type": "string"
+    },
+    "type": "object"
+  },
+  {
+    "items": {
+      "additionalProperties": true,
+      "properties": {
+        "domain": {
+          "type": "string"
+        },
+        "expires": {
+          "type": "number"
+        },
+        "httpOnly": {
+          "type": "boolean"
+        },
+        "name": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "path": {
+          "type": "string"
+        },
+        "sameSite": {
+          "type": "string"
+        },
+        "secure": {
+          "type": "boolean"
+        },
+        "value": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "value"
+      ],
+      "type": "object"
+    },
+    "maxItems": 100,
+    "type": "array"
+  }
+]

changedInput schema / properties / cookies / description

Previous value: -"Cookie key-value pairs for authentication (e.g., {\"session-id\": \"abc123\", \"session-token\": \"xyz789\"})"New value: +"Cookies for authentication. Cookies as a {name: value} object (e.g. {\"session-id\": \"abc123\"}) or as a list (max 100) of cookie objects with metadata: {name, value, domain?, path?, secure?, httpOnly?, sameSite?, expires?}."

removedInput schema / properties / cookies / type
```
Removed value: -"object"
```
addedInput schema / properties / domain / maxLength
```
Added value: +255
```
changedInput schema / properties / domain / minLength
```
Previous value: -1New value: +3
```

addedInput schema / properties / expires_at

Added value: +{
+  "description": "Session expiry in ISO 8601 format (e.g., '2026-12-31T23:59:59Z')",
+  "type": "string"
+}

addedInput schema / properties / headers

Added value: +{
+  "additionalProperties": {
+    "type": "string"
+  },
+  "description": "Custom headers sent with this session (e.g., a User-Agent or Authorization header)",
+  "type": "object"
+}

addedInput schema / properties / notes

Added value: +{
+  "description": "Free-text notes about this session",
+  "maxLength": 1000,
+  "type": "string"
+}

addedInput schema / properties / notify_before_expiry

Added value: +{
+  "description": "Notify when the session is about to expire (API default true)",
+  "type": "boolean"
+}

addedInput schema / properties / notify_on_failure

Added value: +{
+  "description": "Notify when session validation fails (API default true)",
+  "type": "boolean"
+}

addedInput schema / properties / organization_id

Added value: +{
+  "description": "Organization to assign the session to (org admins only)",
+  "format": "uuid",
+  "type": "string"
+}

addedInput schema / properties / shared

Added value: +{
+  "description": "Share the session with organization members immediately (API default false)",
+  "type": "boolean"
+}

removedInput schema / properties / user_agent

Removed value: -{
-  "description": "Browser User-Agent string to use with this session",
-  "type": "string"
-}

changedInput schema / required

Previous value: -[
-  "name",
-  "domain",
-  "cookies"
-]New value: +[
+  "name",
+  "domain",
+  "consent"
+]

First observedv1.5.0Jun 12, 2026

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries the full load and does it well: it discloses that cookies are stored securely, that the session is reusable via session_id, that consent=true is mandatory (API rejects with CONSENT_REQUIRED), and that org sharing and auto-refresh/notification flags exist. It doesn't cover what happens on failed validation beyond the notify flag, but this is solid behavioral context for a mutation tool.

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?

Three sentences, front-loaded with the core action and the login-wall use case before prerequisites. The final sentence is a somewhat dense enumeration of optional parameters, but nothing is wasted and it remains scannable.

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 12-parameter mutation tool with no annotations and no output schema, the description covers purpose, prerequisites, consent semantics, and reusability. It implies the returned session_id but doesn't explicitly state what the caller gets back or any failure modes beyond consent — a minor gap, though no output schema exists to fill it.

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

Parameters3/5

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

Schema description coverage is 100%, so all 12 parameters (including nested cookie metadata and the important consent semantics) are already documented in the schema. The description echoes the consent requirement and enumerates optional features, adding orientation but no syntax or meaning beyond the schema — the baseline 3 is appropriate.

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 description opens with a specific verb+resource ('Create a new stored session') and immediately scopes it to authenticated scraping, which cleanly separates it from the session-management siblings (list/get/validate/update/refresh/delete). The purpose and the persistence model are unambiguous 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 states the trigger condition clearly: use this when you need to scrape behind login walls and can supply cookies from a logged-in browser session. It also surfaces the consent prerequisite. It stops short of naming explicit alternatives or when-not-to-use cases (e.g. using a one-off cookie header on alterlab_scrape instead), so it's strong but not complete routing guidance.

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

alterlab_create_session

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools