Docs: Add MCP Server documentation (#707)

## 📝 Description
Addresses #700

## ✅ Checklist
- [X] I have tested this change
- [ ] This change requires documentation update

Author: TomFern

docs/docs/using-semaphore/ai/mcp-server.md

@@ -0,0 +1,189 @@
+---
+description: Connect your AI Agent with Semaphore using an MCP Server
+sidebar_position: 1
+---
+
+# MCP Server
+
+This page explains how Semaphore's MCP Server works, how to configure your clients/agents, and what capabilities are available.
+
+:::info Request access to this feature
+
+If you want to try the MCP Server, contact `support@semaphore.io` so we can enable this feature in your organization at no cost.
+
+:::
+
+## Overview
+
+[MCP servers](https://modelcontextprotocol.info/) (Model Context Protocol servers) connect AI models to external data and tools through a standardized interface. They provide structured, real-time context-like data from APIs so models can retrieve accurate information and perform actions securely and consistently.
+
+You can connect your favorite AI agent with Semaphore using the official MCP Server. This allows the AI agent or IDE to access the activity in your organization using a conversational interface. 
+
+With MCP, you can now ask your AI agent why your build failed and to provide a fix.
+
+## MCP Server Capabilities {#tools}
+
+Semaphore's MCP Server provides **read-only access** to your Semaphore organization via the following tools:
+
+- `echo`: Returns the provided `message` verbatim (handy for smoke tests) 
+- `organizations_list`: Lists organizations that the user can access
+- `projects_list`: List projects that belong to a specific organization
+- `projects_search`: Search projects inside an organization by project name, repository URL, or description
+- `workflows_search`: Search recent workflows for a project (most recent first) 
+- `pipelines_list`: List pipelines associated with a workflow (most recent first)
+- `pipeline_jobs`: List jobs belonging to a specific pipeline 
+- `jobs_describe`: Describes a job, surfacing agent details, and lifecycle timestamps
+- `jobs_logs`: Fetches job logs. For cloud jobs, it streams loghub events. For self-hosted jobs, returns a URL where logs can be fetched
+
+See [example prompts](#examples) to see a bit of what's possible.
+
+## Configure your AI Agent or IDE
+
+Access to the MCP Server is controlled via an API Token. You can obtain your API token in two ways:
+
+- [Personal API Token](../user-management#profile-token): if you don't know your personal API token, you can reset it and obtain a new one
+- [Service Account](../service-accounts): create a service account with *Member* role and use its API token
+
+Both types of tokens are used to communicate with the Semaphore MCP Server endpoint: `https://mcp.semaphoreci.com/mcp`
+
+If you have problems connecting to the MCP Server, see [troubleshooting](#troubleshooting).
+
+
+### Claude Code {#claude-code}
+
+<Steps>
+
+1. Export an environment variable with your API token
+
+    ```shell
+    export SEMAPHORE_API_TOKEN=my-token
+    ```
+
+2. Add the MCP Server to Claude Code
+
+    ```shell
+    claude mcp add semaphore https://mcp.semaphoreci.com/mcp \
+      --scope user --transport http \
+      --header "Authorization: Bearer $SEMAPHORE_API_TOKEN"
+    ```
+
+3. If you have a session open, restart Claude Code
+
+</Steps>
+
+### OpenAI's Codex {#codex}
+
+<Steps>
+
+1. Open `$HOME/.codex/config.toml` and add the following lines to the config file
+
+
+    ```toml title="Semaphore MCP Configuration for Codex"
+    [mcp_servers.semaphore]
+    url = "https://mcp.semaphoreci.com/mcp"
+    bearer_token_env_var = "SEMAPHORE_API_TOKEN"
+    startup_timeout_sec = 30
+    tool_timeout_sec = 300
+    ```
+
+    :::note Environment variable name
+
+    The `bearer_token_env_var` value references the name of the environment variable that contains the actual API token value. It *is not* set to the actual API token value.
+
+    :::
+
+2. Export an environment variable with your API token. The *name of the environment variable* must be equal to the `bearer_token_env_var` in the previous step. Consider adding this line to your `.bashrc` (or similar)
+
+    ```shell
+    export SEMAPHORE_API_TOKEN=my-token
+    ```
+
+3. Start Codex normally
+
+</Steps>
+
+### VSCode Codex Extension {#vscode-codex}
+
+<Steps>
+
+1. Install the [VSCode Codex Extension](https://developers.openai.com/codex/ide/)
+
+2. Set up Codex as shown [above in OpenAI's Codex](#codex). Alternatively, in VS Code press the Gear icon → **MCP settings** → **Open config.toml** and add the lines shown in the [Codex Setup](#codex)
+
+    ```toml title="Semaphore MCP Configuration for Codex"
+    [mcp_servers.semaphore]
+    url = "https://mcp.semaphoreci.com/mcp"
+    bearer_token_env_var = "SEMAPHORE_API_TOKEN"
+    startup_timeout_sec = 30
+    tool_timeout_sec = 300
+    ```
+
+3. Close VS Code
+
+4. Export an environment variable with your API token. The *name of the environment variable* must be equal to the `bearer_token_env_var` in the `config.toml`. Consider adding this line to your `.bashrc` (or similar)
+
+    ```shell
+    export SEMAPHORE_API_TOKEN=my-token
+    ```
+
+5. Start VS Code from the command line, in the same shell session where you set the environment variable. This ensures VS Code can have access to the API token
+
+    ```shell
+    code path/to/project
+    ```
+
+    :::note
+
+      Due to current limitations of the Codex extension for VS Code, if you start VS Code in any other way except from the terminal session where the SEMAPHORE_API_TOKEN variable has the correct value, the Semaphore MCP server **will not work**.
+
+    :::
+
+
+</Steps>
+
+## Example Prompts {#examples}
+
+The MCP Server provides access to your Semaphore organization (assuming the MCP Server is enabled for your organization).
+
+
+Here are a few example prompts you can use to interact with your projects, pipelines, and jobs. Use them as starting points to interact with Semaphore. Some prompts might require an API Token with [Admin Role](../rbac#org-admin).
+
+| Task | Prompt |
+|------|--------|
+| List organizations the Agent has access to | "List organizations you have access to" |
+| Save the organization and project IDs in `AGENTS.md` (speeds up tasks and saves tokens) | "Find the current project in Semaphore and obtain the organization id and project id. Save the values in AGENTS.md for future reference" |
+| Understand what the pipeline does | "Describe what my pipeline does for this project on Semaphore" |
+| Troubleshoot failed tests | "Help me figure out why have my test failed on Semaphore" |
+| Troubleshoot failed builds | "Why did my build fail?" |
+| Retrieve the logs for a job |  "Show me the logs for the build job in the latest workflow in Semaphore" |
+
+## Troubleshooting {#troubleshooting}
+
+### Codex fails to connect
+
+**Symptom**: When you start Codex, you see the following message:
+
+```text
+■ MCP client for `semaphore` failed to start: handshaking with MCP server failed: Send message error Transport
+[rmcp::transport::worker::WorkerTransport<rmcp::transport::streamable_http_client::StreamableHttpClientWorker<reqwest::async_impl::client::Client>>] error:
+Client error: HTTP status client error (401 Unauthorized) for url (https://mcp.semaphoreci.com/mcp), when send initialize request
+```
+
+**Solution**: This usually means the environment variable with the Semaphore API Token is not correctly loaded. Check your `config.toml` to learn what the environment variable name and ensure you are setting it correctly in your shell before starting Codex.
+
+
+### VS Code fails to connect
+
+**Symptom**: Your Codex extension in VS Code fails to connect with the MCP server.
+
+**Solution**: This usually means that VS Code does not have access to the environment variable with the Semaphore API Token. Ensure you have set the environment variable as per `config.toml` in your shell, and that you are actually starting VS Code from that very same shell session. Starting VS Code by any other means causes Codex to fail the connection.
+
+## See also
+
+- [User management](../user-management)
+- [Service accounts](../service-accounts)
+
+
+
+
+

docs/docs/using-semaphore/service-accounts.md

@@ -6,8 +6,12 @@ description: Enable programmatic access to the API via service accounts
 
 A service account allows you to programmatically access the API.
 
+:::info Request access to this feature
+
 To have this feature enabled for your organization, please contact us at support@semaphoreci.com and include a short description of your use case.
 
+:::
+
 ## Overview
 
 Service accounts are special users that can only be used to consume the [Semaphore API](../reference/api). Service accounts cannot be used to log in to the Semaphore UI.

docs/docs/using-semaphore/user-management.md

@@ -56,15 +56,15 @@ To change your Semaphore email address, follow these steps:
 
 </Steps>
 
-### How to reset your access token {#profile-token}
+### How to reset your personal API token {#profile-token}
 
 :::warning
 
 Changing your access token will revoke access to the [Semaphore API](../reference/api) and access via the [Semaphore CLI](../reference/semaphore-cli). Only reset your token if you have lost access to it or suspect someone else has been using it on your behalf.
 
 :::
 
-To reset your Semaphore access token, follow these steps:
+To reset your Semaphore API token, follow these steps:
 
 <Steps>
 

docs/sidebars.js

@@ -82,7 +82,20 @@ const sidebars = {
           'using-semaphore/tasks',
         ]
       },
+      
 
+      {
+        type: 'category',
+        label: 'AI-Driven Development',
+        collapsed: true,
+        items: [
+          {
+            type: 'autogenerated',
+            dirName: 'using-semaphore/ai',
+          }
+        ]
+      },
+      
 
       {
         type: 'category',

docs/versioned_docs/version-CE/using-semaphore/user-management.md

@@ -56,15 +56,15 @@ To change your Semaphore email address, follow these steps:
 
 </Steps>
 
-### How to reset your access token {#profile-token}
+### How to reset your personal API token {#profile-token}
 
 :::warning
 
 Changing your access token will revoke access to the [Semaphore API](../reference/api) and access via the [Semaphore CLI](../reference/semaphore-cli). Only reset your token if you have lost access to it or suspect someone else has been using it on your behalf.
 
 :::
 
-To reset your Semaphore access token, follow these steps:
+To reset your Semaphore API token, follow these steps:
 
 <Steps>
 

docs/versioned_docs/version-EE/using-semaphore/user-management.md

@@ -56,15 +56,15 @@ To change your Semaphore email address, follow these steps:
 
 </Steps>
 
-### How to reset your access token {#profile-token}
+### How to reset your personal API token {#profile-token}
 
 :::warning
 
 Changing your access token will revoke access to the [Semaphore API](../reference/api) and access via the [Semaphore CLI](../reference/semaphore-cli). Only reset your token if you have lost access to it or suspect someone else has been using it on your behalf.
 
 :::
 
-To reset your Semaphore access token, follow these steps:
+To reset your Semaphore API token, follow these steps:
 
 <Steps>