# Permissions

This page covers who has access to what, how to get access, and how authentication works for both end users and the people who manage the server.

***

## How Users Log In

Regular Mailworks employees don't need to do anything special. When they use Claude and it needs to access Google Docs, Drive, or Sheets, the server handles authentication automatically:

1. The user is redirected to Google's login page.
2. They sign in with their `@themailworks.com` account.
3. The server stores their session so they don't have to log in again for 30 days.

The Google OAuth app is configured as **Internal**, which means only `@themailworks.com` accounts can log in. External Google accounts are blocked at Google's level.

### Deployment and Change Control

All code changes go through peer review and automated testing in GitHub before they can be merged. Deployments to production are manual-only, never automatic. Every deployment is recorded with who deployed it, what version, and when.

A weekly automated check watches the upstream open-source project for security fixes and new releases.

### SOC 2 Alignment

| Area                     | How It's Handled                                                                                                       |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| Access control           | Only `@themailworks.com` accounts. Sessions are isolated per user. Credentials are encrypted and expire after 30 days. |
| Audit logging            | Every tool call and login is logged to Splunk. Document content is never logged.                                       |
| Change management        | Peer review and automated tests required. Manual deploy gate.                                                          |
| Availability             | Runs across multiple AWS availability zones. Sessions survive container restarts.                                      |
| Vulnerability management | Images scanned on every build. Dependencies version-pinned. Upstream monitored weekly.                                 |

***

## GCP Project Details

The Google OAuth app and the Google APIs that the server calls all live in one Google Cloud project.

| Field        | Value                                                           |
| ------------ | --------------------------------------------------------------- |
| Project Name | `CUSTOM-MCP-SERVER-MAILWORKS`                                   |
| Organization | `themailworks.com`                                              |
| Purpose      | Hosts the OAuth app and the Google APIs used by the MCP server. |

### Who has access

| Role          | Account                                |
| ------------- | -------------------------------------- |
| Project Owner | `preetham.baswapuram@themailworks.com` |

Regular Mailworks employees do not automatically have access to this project. You need explicit IAM permissions granted at the project or organization level. If you need access, contact Preetham.

### APIs currently enabled

| API               |
| ----------------- |
| Google Docs API   |
| Google Drive API  |
| Google Sheets API |

**If you're enabling a new tool family** (e.g., Calendar, Gmail), the corresponding API must be turned on in this project first. See the Future Tools reference for the API links for each service.

***

## AWS Access

The MCP server infrastructure lives in AWS account `573946584375` in `us-east-1`. Access is managed through IAM Identity Center (SSO), meaning each person logs in with their own credentials.

### How to log in (daily)

```bash
aws sso login --profile mcp-prod
```

This opens a browser for authentication. Once logged in, your session lasts about 8 hours. After that, run the command again.

### AWS CLI profile setup

Add this to `~/.aws/config`:

```ini
[profile mcp-prod]
sso_start_url  = https://d-9067a9589b.awsapps.com/start
sso_region     = us-east-1
sso_account_id = 573946584375
sso_role_name  = TerraformOperator
region         = us-east-1
output         = json
```

Then set it as your default:

```bash
export AWS_PROFILE=mcp-prod
```

### Permission levels

| Role                | Who gets it                                               | What it can do                                                        |
| ------------------- | --------------------------------------------------------- | --------------------------------------------------------------------- |
| `TerraformOperator` | Engineers who run Terraform or respond to incidents       | Full access to ECS, Secrets Manager, CloudWatch, S3 state, ECR        |
| `ReadOnly`          | Developers or analysts who need to inspect but not change | View ECS, CloudWatch logs, service status (cannot read secret values) |

### Emergency access (break-glass)

If SSO is completely down or the identity provider is unreachable, the AWS root account email holder can log into the root account as a last resort to restore IAM Identity Center. This should only happen in a genuine lockout. The root account must have MFA enabled, and at least two people should know the recovery path (not the credentials themselves).

***

## New Team Member Setup

This checklist is for people who will be managing or updating the server. Regular users of the MCP server don't need any of this. Work through the items in order.

### 1. AWS Account Access

**What it is:** Console and CLI access to the AWS account.

**How to get it:**

1. Send a message to the platform team with your full name, company email, and the role you need (`TerraformOperator` or `ReadOnly`).
2. You'll receive an email invitation with a one-time activation link.
3. Follow the link and set a password.
4. Install the AWS CLI: `brew install awscli` (macOS) or follow [the official instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
5. Add the profile to `~/.aws/config` (see above).
6. Log in: `aws sso login --profile mcp-prod`
7. Verify: `aws sts get-caller-identity --profile mcp-prod`

### 2. Terraform State Access

**What it is:** Read access to the shared Terraform state file in S3.

**How to get it:** Automatically included with `TerraformOperator`. After AWS access is active:

```bash
cd /workspace/mcp/mcp-terraform && terraform init
```

If `init` fails with an S3 error, make sure your SSO session is active and your profile is exported.

### 3. Terraform CLI

**What it is:** The Terraform tool itself, version >= 1.5.

**How to get it:**

Option A (preferred):

```bash
brew install mise
mise install   # run inside /workspace/mcp/mcp-terraform
```

Option B:

```bash
brew tap hashicorp/tap
brew install hashicorp/tap/terraform
terraform version   # confirm >= 1.5
```

### 4. GitHub Repository Access

**What it is:** Access to `themailworks/mcp-google` (the application code) and `themailworks/mcp-terraform` (the infrastructure code).

**How to get it:**

1. Give your GitHub username to the platform team.
2. They'll add you to the `themailworks` organization.
3. Accept the invitation email from GitHub.

Read access is enough for monitoring CI/CD. Write access is needed to push code or trigger deploys.

### 5. Secrets Manager Access

**What it is:** Ability to read secret values during an incident.

**How to get it:** Included with `TerraformOperator`. Verify:

```bash
aws secretsmanager get-secret-value \
  --secret-id /prod/mcp/google-oauth \
  --query 'SecretString' --profile mcp-prod
```

If you have `ReadOnly` permissions and need secret access for on-call, request the `SecretsReadOnly` policy from the platform admin.

### 6. CloudWatch Logs

**What it is:** Access to view container logs.

**How to get it:** Included with both `TerraformOperator` and `ReadOnly`. Verify:

```bash
aws logs tail /ecs/prod/mcp/google_workspace --since 5m --profile mcp-prod
```

### 7. Splunk Cloud

**What it is:** Access to query audit events.

**How to get it:**

1. Contact whoever administers The Mailworks Splunk Cloud instance.
2. Request read access to the `mcp_audit` index.
3. Verify: `index=mcp_audit earliest=-15m | stats count`

### 8. Alert Notifications

**What it is:** Receiving alarm notifications when the server has a problem.

**How to get it:**

1. Ask the platform team to add your email or a Slack channel to the SNS topic `arn:aws:sns:us-east-1:573946584375:MCPAlerts`.
2. Click the confirmation link in the subscription email.

If your team uses PagerDuty or OpsGenie, provide the integration endpoint to the platform admin instead.

### 9. ECR Access (optional, for building container images)

**What it is:** Permission to push Docker images to the container registry.

**When you need it:** Normally you don't. Deployments go through GitHub Actions. Only request this if you need to push a test image manually.

**How to get it:**

1. Request the `ECRPush` permission set.
2. Authenticate Docker:

```bash
aws ecr get-login-password --region us-east-1 --profile mcp-prod \
  | docker login --username AWS --password-stdin \
    573946584375.dkr.ecr.us-east-1.amazonaws.com
```

### Verify everything works

Run all of these. Each should succeed without errors:

```bash
# 1. AWS identity
aws sts get-caller-identity --profile mcp-prod

# 2. Terraform state
cd /workspace/mcp/mcp-terraform && terraform init

# 3. ECS cluster is visible
aws ecs describe-clusters --clusters prod-mcp-cluster \
  --query 'clusters[0].{name:clusterName,status:status}' --profile mcp-prod

# 4. Logs work
aws logs tail /ecs/prod/mcp/google_workspace --since 1m --profile mcp-prod

# 5. Server is healthy
curl -sI https://google.mcp.themailworks.com/health
```

If any step fails, re-read the matching section above or ask the platform team for help.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://knowledge.themailworks.com/mcp-server/permissions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.